phlex-reactive 0.13.4 → 0.14.0

data/lib/phlex/reactive/test_helpers/system/reactive_requests_matcher.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Phlex
+  module Reactive
+    module TestHelpers
+      module System
+        # The waiting matcher behind have_reactive_requests (issue #279). Reads the
+        # client's per-kind request totals (<html data-reactive-requests>, JSON)
+        # AND the in-flight marker in ONE evaluate_script per poll, and holds once
+        # the selected total equals `expected` with the layer idle, so a request
+        # still in flight is never counted early. It cannot see a request that has
+        # not STARTED yet (a debounced trigger, or the defer an action's reply is
+        # about to start): barrier on the UI outcome first for those.
+        #
+        # Totals only grow until reset_reactive_requests!, so a total ABOVE the
+        # expectation is terminal: the matcher fails at once instead of waiting out
+        # the budget. A plain class (no RSpec::Matchers.define), like
+        # ReactiveValueMatcher, so System stays loadable under Capybara alone.
+        class ReactiveRequestsMatcher
+          KINDS = %i[action defer].freeze
+
+          def initialize(expected, kind: nil, wait: nil)
+            unless kind.nil? || KINDS.include?(kind)
+              raise ArgumentError, "unknown reactive request kind #{kind.inspect} (expected one of #{KINDS.inspect} or nil)"
+            end
+
+            @expected = Integer(expected)
+            @kind = kind
+            @wait = wait
+          end
+
+          def matches?(page)
+            @page = page
+            poll_until do
+              read_state
+              break false if selected > @expected
+
+              selected == @expected && !@active
+            end
+          end
+
+          # RSpec's required negated-matcher protocol name, not a predicate we pick.
+          # rubocop:disable-next Naming/PredicatePrefix
+          def does_not_match?(page)
+            @page = page
+            poll_until do
+              read_state
+              selected != @expected && !@active
+            end
+          end
+
+          def failure_message
+            with_gate_hint(
+              "expected #{@expected} reactive #{noun} (#{scope}), got #{selected} — totals #{totals_str}"
+            )
+          end
+
+          def failure_message_when_negated
+            with_gate_hint(
+              "expected the reactive request count (#{scope}) NOT to be #{@expected}, but it was — totals #{totals_str}"
+            )
+          end
+
+          private
+
+          # A closed verbose gate is the usual cause of an unexpected zero: say so.
+          def with_gate_hint(message)
+            return message if @verbose
+
+            "#{message}. The verbose gate is closed, so the client is not counting: it writes " \
+              "<html #{REQUESTS_ATTR}> only under Phlex::Reactive.verbose_errors (on in dev/test " \
+              "by default) or data-reactive-verbose on <html>"
+          end
+
+          def read_state
+            raw = @page.evaluate_script(<<~JS)
+              (() => {
+                const html = document.documentElement
+                return {
+                  requests: html.getAttribute(#{REQUESTS_ATTR.to_json}),
+                  active: html.hasAttribute(#{ACTIVE_MARKER.to_json}),
+                  verbose: html.hasAttribute("data-reactive-verbose") ||
+                    !!document.querySelector('[data-reactive-verbose="true"]'),
+                }
+              })()
+            JS
+            raw = {} unless raw.is_a?(::Hash)
+            @verbose = raw["verbose"] == true
+            @totals = System.parse_reactive_requests(raw["requests"])
+            @active = raw["active"] == true
+          end
+
+          def selected = @kind ? @totals[@kind] : @totals.values.sum
+
+          def scope = @kind ? "kind: #{@kind.inspect}" : "any kind"
+
+          def noun = @expected == 1 ? "request" : "requests"
+
+          def totals_str = "{#{@totals.map { |k, v| "#{k}: #{v}" }.join(", ")}}"
+
+          # Same bounded, monotonic-clock poll as ReactiveValueMatcher. A `break
+          # false` inside the block ends the poll early (a terminal mismatch).
+          def poll_until
+            deadline = now + (@wait || ::Capybara.default_max_wait_time)
+            loop do
+              return true if yield
+              return false if now >= deadline
+
+              sleep 0.05
+            end
+          end
+
+          def now = ::Process.clock_gettime(::Process::CLOCK_MONOTONIC)
+        end
+      end
+    end
+  end
+end

data/lib/phlex/reactive/test_helpers/system.rb

@@ -36,6 +36,30 @@ module Phlex
         # twin of wait_for_turbo watching the Turbo progress bar.
         ACTIVE_MARKER = "data-reactive-active"
 
+        # The <html> attribute the client keeps its per-kind request totals in
+        # (issue #279), as JSON ({"action":1,"defer":0}). Lockstep with
+        # reactive_controller.js REQUESTS_ATTR. Written only under the verbose
+        # gate (dev/test by default).
+        REQUESTS_ATTR = "data-reactive-requests"
+
+        # Parse the attribute value into { action:, defer: } Integers — zeros for
+        # an absent or garbled value. Shared by the helpers and
+        # ReactiveRequestsMatcher.
+        def self.parse_reactive_requests(raw)
+          parsed = raw.is_a?(::String) ? ::JSON.parse(raw) : {}
+          parsed = {} unless parsed.is_a?(::Hash)
+          { action: reactive_request_total(parsed["action"]), defer: reactive_request_total(parsed["defer"]) }
+        rescue ::JSON::ParserError
+          { action: 0, defer: 0 }
+        end
+
+        # One total as an Integer. Only a number or a numeric string counts; any
+        # other JSON value (array, object, boolean, null) is garbled, so zero.
+        def self.reactive_request_total(value)
+          value.is_a?(::Numeric) || value.is_a?(::String) ? value.to_i : 0
+        end
+        private_class_method :reactive_request_total
+
         # Block until the reactive layer is IDLE — every dispatch round trip and
         # deferred render has settled and the <html data-reactive-active> marker is
         # gone. The system-test twin of wait_for_turbo (which watches the Turbo
@@ -92,6 +116,42 @@ module Phlex
         def have_reactive_text(id, value, **)
           have_css("##{id}", text: value, **)
         end
+
+        # How many reactive requests the page has made since the last
+        # reset_reactive_requests! (or since the page loaded), per kind (issue
+        # #279):
+        #
+        #   reactive_request_count # => { action: 1, defer: 0 }
+        #
+        # A snapshot, not a wait — barrier on wait_for_reactive (or use
+        # have_reactive_requests) before reading it after a gesture.
+        def reactive_request_count
+          System.parse_reactive_requests(
+            page.evaluate_script("document.documentElement.getAttribute(#{REQUESTS_ATTR.to_json})")
+          )
+        end
+
+        # Baseline the request totals to zero. The attribute IS the client's
+        # store, so writing zeros re-baselines it — including after a Turbo Drive
+        # visit, where the <html> element (and its totals) survives navigation.
+        def reset_reactive_requests!
+          zeros = { action: 0, defer: 0 }.to_json
+          page.execute_script("document.documentElement.setAttribute(#{REQUESTS_ATTR.to_json}, '#{zeros}')")
+          nil
+        end
+
+        # Assert (waiting) that exactly `count` reactive requests were made — of
+        # `kind` (:action or :defer), or of any kind — since the last reset, AND
+        # that nothing is still in flight. Fails at once if the count overshoots
+        # (totals only grow until a reset).
+        #
+        #   reset_reactive_requests!
+        #   find("#open-panel").click
+        #   expect(page).to have_reactive_requests(1)
+        #   expect(page).to have_reactive_requests(0, kind: :defer)
+        def have_reactive_requests(count, kind: nil, timeout: nil, wait: nil)
+          ReactiveRequestsMatcher.new(count, kind:, wait: timeout || wait)
+        end
         # rubocop:enable Naming/PredicatePrefix
 
         # A waiting matcher that asserts a field's live `.value` PROPERTY (issue
@@ -190,3 +250,5 @@ module Phlex
     end
   end
 end
+
+require "phlex/reactive/test_helpers/system/reactive_requests_matcher"

data/lib/phlex/reactive/version.rb

@@ -2,6 +2,6 @@
 
 module Phlex
   module Reactive
-    VERSION = "0.13.4"
+    VERSION = "0.14.0"
   end
 end

data/lib/phlex/reactive.rb

@@ -133,6 +133,12 @@ module Phlex
       # ActionPolicy::Unauthorized, ...).
       attr_accessor :authorization_errors
 
+      # Import maps `phlex_reactive:doctor` checks for the `phlex/reactive/early`
+      # pin (issue #307): a callable returning `{ name => Importmap::Map }`, for
+      # an app with more than one map (one per entry point). nil (the default)
+      # checks `Rails.application.importmap` only.
+      attr_accessor :importmaps
+
       # The path the action endpoint is mounted at. Default "/reactive/actions".
       # Set before boot if it collides with an app route. The client runtime
       # reads it from a <meta name="phlex-reactive-action-path"> tag if present,
@@ -532,6 +538,29 @@ module Phlex
         instance.view_context
       end
 
+      # --- Early triggers (issue #273) -----------------------------------
+
+      # How long (ms) a trigger captured by phlex/reactive/early before the
+      # controller connected stays replayable. Older entries are dropped on
+      # connect (warned under data-reactive-verbose): a click from long ago must
+      # not fire a request out of nowhere. The client reads it from a meta tag
+      # in the host layout (the engine can't inject into it):
+      #   <meta name="phlex-reactive-early-ttl" content="<%= Phlex::Reactive.early_event_ttl_ms %>">
+      # Without the meta the client uses the same 10 s default. nil resets.
+      # Validated at assignment: the client reads a non-positive TTL as "use
+      # the default", so 0 can never mean "replay nothing" — fail here instead.
+      def early_event_ttl_ms=(value)
+        unless value.nil? || (value.is_a?(Integer) && value.positive?)
+          raise ArgumentError, "early_event_ttl_ms must be a positive Integer (milliseconds) or nil, got #{value.inspect}"
+        end
+
+        @early_event_ttl_ms = value
+      end
+
+      def early_event_ttl_ms
+        @early_event_ttl_ms ||= 10_000
+      end
+
       # --- Deferred reply segments (issue #165) --------------------------
 
       # Lifetime (seconds) of a defer token. It only needs to cover the
@@ -552,6 +581,44 @@ module Phlex
         @defer_path ||= "/reactive/defer"
       end
 
+      # The path prefix of the cacheable-fragment GET endpoint (issue #277):
+      # GET <fragment_path>/<signed id>. Default "/reactive/fragment"; set
+      # before boot if it collides. The shell renders the full URL, but the
+      # client only fetches one under the path it knows: when you change this,
+      # also render <meta name="phlex-reactive-fragment-path" content="…">.
+      attr_writer :fragment_path
+
+      def fragment_path
+        @fragment_path ||= "/reactive/fragment"
+      end
+
+      # The longest max-age (seconds) a `reactive_lazy cache:` component may
+      # ask the browser to keep its fragment for. A component declaring more
+      # is answered with this cap. Within max-age the browser reuses its copy
+      # WITHOUT asking the server — so this also bounds how long a revoked
+      # permission can keep showing a stale fragment. Default 1 hour; nil
+      # restores it; 0 makes every cached fragment revalidate on each use.
+      def fragment_cache_max_age_limit=(value)
+        seconds = value.is_a?(ActiveSupport::Duration) && value.to_i == value ? value.to_i : value
+        unless seconds.nil? || (seconds.is_a?(::Integer) && !seconds.negative?)
+          raise ArgumentError,
+            "Phlex::Reactive.fragment_cache_max_age_limit must be a whole, non-negative number of seconds " \
+            "(or nil for the default) — got #{value.inspect}"
+        end
+
+        @fragment_cache_max_age_limit = seconds
+      end
+
+      def fragment_cache_max_age_limit
+        @fragment_cache_max_age_limit ||= 3600
+      end
+
+      # The deterministic, no-expiry, purpose-scoped fragment id of an identity
+      # payload, and its verification (issue #277). See Phlex::Reactive::Fragment.
+      def sign_fragment(payload) = Fragment.sign(payload)
+
+      def verify_fragment(id) = Fragment.verify(id)
+
       # How deferred segments reach the actor: :auto (push iff capable, else
       # pull), :fetch (always pull), :stream (push; degrades to pull with a
       # warning when the capability is absent). Validated at assignment — a
@@ -1056,6 +1123,7 @@ module Phlex
       # The controller a correctly-mounted action path resolves to. Used by the
       # route guard below.
       ACTIONS_CONTROLLER = "phlex/reactive/actions"
+      FRAGMENTS_CONTROLLER = "phlex/reactive/fragments"
 
       # True when a POST to `path` resolves to the gem's ActionsController. A host
       # catch-all route (match "*path", ...) appended above the engine's route
@@ -1076,6 +1144,20 @@ module Phlex
         false
       end
 
+      # Does GET <fragment_path>/<id> resolve to the gem's FragmentsController
+      # (issue #277)? A host GET catch-all shadows it otherwise, and every
+      # `reactive_lazy cache:` fetch then gets the host's fallback page. The
+      # doctor reports it, like the defer route.
+      def fragment_route_ok?(path = fragment_path)
+        return false unless defined?(::Rails) && ::Rails.application
+
+        ensure_routes_loaded
+        recognized = ::Rails.application.routes.recognize_path("#{path}/probe", method: :get)
+        recognized[:controller] == FRAGMENTS_CONTROLLER
+      rescue ActionController::RoutingError, ActiveRecord::RecordNotFound
+        false
+      end
+
       # Log a clear warning (once, at boot) when the action path doesn't resolve
       # to the gem controller — pointing at the catch-all shadow rather than
       # leaving an adopter to guess. Called from the engine's after_initialize.
@@ -1184,6 +1266,8 @@ loader.ignore("#{lib}/phlex/reactive/test_helpers/matchers.rb")
 # only when Capybara is present, so the loader must ignore it (otherwise an
 # eager-load in production would define browser helpers with no Capybara).
 loader.ignore("#{lib}/phlex/reactive/test_helpers/system.rb")
+# ...and its matcher subdirectory (issue #279), required by system.rb itself.
+loader.ignore("#{lib}/phlex/reactive/test_helpers/system")
 # The MCP diagnostic tool tree (issue #168) subclasses the OPTIONAL `mcp` gem's
 # constants (MCP::Tool) at class-definition time, so the whole mcp/ subdirectory
 # must stay out of the autoloader — Phlex::Reactive::MCP.load! requires it in

data/lib/tasks/phlex_reactive.rake

@@ -12,14 +12,18 @@ namespace :phlex_reactive do
     abort unless Phlex::Reactive::Doctor.run
   end
 
-  desc "List every declared reactive action (component | action | params | file:line | auth); FORMAT=json for tooling"
+  desc "List every declared reactive action (component | action | params | file:line | auth); " \
+       "FORMAT=json for tooling, UNVERIFIED=1 for only the unverified rows"
   task actions: :environment do
     # eager_load! so every app component is in the Streamable registry the
     # Inspector reads. Plain text by default (no ANSI, like the doctor);
     # FORMAT=json emits a parseable array for tooling. Names/paths/schemas only.
+    # UNVERIFIED=1 keeps only actions with neither a detected authorization call
+    # nor a skip_verify_authorized — the review queue (issue #278).
     Rails.application.eager_load!
     format = ENV["FORMAT"].to_s.downcase == "json" ? :json : :text
-    puts Phlex::Reactive::Inspector::Report.actions(Phlex::Reactive::Inspector.components, format:)
+    unverified_only = %w[1 true yes].include?(ENV["UNVERIFIED"].to_s.downcase)
+    puts Phlex::Reactive::Inspector::Report.actions(Phlex::Reactive::Inspector.components, format:, unverified_only:)
   end
 
   desc "Fuzzy-find a reactive component and print its actions with method-definition source — phlex_reactive:find[query]"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.13.4
+  version: 0.14.0
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -118,6 +118,7 @@ files:
 - README.md
 - app/assets/stylesheets/phlex/reactive/effects.css
 - app/controllers/phlex/reactive/actions_controller.rb
+- app/controllers/phlex/reactive/fragments_controller.rb
 - app/javascript/phlex/reactive/compute.js
 - app/javascript/phlex/reactive/compute.min.js
 - app/javascript/phlex/reactive/compute.min.js.map
@@ -127,12 +128,43 @@ files:
 - app/javascript/phlex/reactive/confirm_predicate.js
 - app/javascript/phlex/reactive/confirm_predicate.min.js
 - app/javascript/phlex/reactive/confirm_predicate.min.js.map
+- app/javascript/phlex/reactive/core.js
+- app/javascript/phlex/reactive/core.min.js
+- app/javascript/phlex/reactive/core.min.js.map
+- app/javascript/phlex/reactive/early.js
+- app/javascript/phlex/reactive/early.min.js
+- app/javascript/phlex/reactive/early.min.js.map
+- app/javascript/phlex/reactive/features/bindings.js
+- app/javascript/phlex/reactive/features/bindings.min.js
+- app/javascript/phlex/reactive/features/bindings.min.js.map
+- app/javascript/phlex/reactive/features/compute.js
+- app/javascript/phlex/reactive/features/compute.min.js
+- app/javascript/phlex/reactive/features/compute.min.js.map
+- app/javascript/phlex/reactive/features/defer.js
+- app/javascript/phlex/reactive/features/defer.min.js
+- app/javascript/phlex/reactive/features/defer.min.js.map
+- app/javascript/phlex/reactive/features/devtools.js
+- app/javascript/phlex/reactive/features/devtools.min.js
+- app/javascript/phlex/reactive/features/devtools.min.js.map
+- app/javascript/phlex/reactive/features/effects.js
+- app/javascript/phlex/reactive/features/effects.min.js
+- app/javascript/phlex/reactive/features/effects.min.js.map
+- app/javascript/phlex/reactive/features/form.js
+- app/javascript/phlex/reactive/features/form.min.js
+- app/javascript/phlex/reactive/features/form.min.js.map
+- app/javascript/phlex/reactive/features/hints.js
+- app/javascript/phlex/reactive/features/hints.min.js
+- app/javascript/phlex/reactive/features/hints.min.js.map
+- app/javascript/phlex/reactive/features/persist.js
+- app/javascript/phlex/reactive/features/persist.min.js
+- app/javascript/phlex/reactive/features/persist.min.js.map
 - app/javascript/phlex/reactive/inspect.js
 - app/javascript/phlex/reactive/inspect.min.js
 - app/javascript/phlex/reactive/inspect.min.js.map
 - app/javascript/phlex/reactive/reactive_controller.js
 - app/javascript/phlex/reactive/reactive_controller.min.js
 - app/javascript/phlex/reactive/reactive_controller.min.js.map
+- app/javascript/phlex/reactive/runtime.js
 - lib/generators/phlex/reactive/claude/USAGE
 - lib/generators/phlex/reactive/claude/claude_generator.rb
 - lib/generators/phlex/reactive/component/USAGE
@@ -160,11 +192,15 @@ files:
 - lib/phlex/reactive/component/identity.rb
 - lib/phlex/reactive/component/lazy.rb
 - lib/phlex/reactive/component/registry.rb
+- lib/phlex/reactive/component/selection.rb
 - lib/phlex/reactive/defer.rb
 - lib/phlex/reactive/deferred_render_job.rb
 - lib/phlex/reactive/doctor.rb
+- lib/phlex/reactive/doctor/fiber_isolation.rb
+- lib/phlex/reactive/dormant.rb
 - lib/phlex/reactive/effects.rb
 - lib/phlex/reactive/engine.rb
+- lib/phlex/reactive/fragment.rb
 - lib/phlex/reactive/inspector.rb
 - lib/phlex/reactive/inspector/report.rb
 - lib/phlex/reactive/js.rb
@@ -191,6 +227,7 @@ files:
 - lib/phlex/reactive/test_helpers.rb
 - lib/phlex/reactive/test_helpers/matchers.rb
 - lib/phlex/reactive/test_helpers/system.rb
+- lib/phlex/reactive/test_helpers/system/reactive_requests_matcher.rb
 - lib/phlex/reactive/version.rb
 - lib/tasks/phlex_reactive.rake
 homepage: https://github.com/zoolutions/phlex-reactive