phlex-reactive 0.4.8 → 0.9.1

data/lib/phlex/reactive.rb

@@ -29,13 +29,62 @@ module Phlex
     class Error < StandardError; end
 
     # Raised when a signed identity token fails verification (tampered, expired,
-    # or signed with a different key).
-    class InvalidToken < Error; end
+    # or signed with a different key) — or when a verified token names a class
+    # that doesn't resolve to a reactive component. `diagnostic` classifies the
+    # cause (:tampered, :unknown_class, :not_reactive_class) so the endpoint can
+    # render a verbose_errors body explaining WHICH failure this was.
+    class InvalidToken < Error
+      attr_reader :diagnostic
+
+      def initialize(msg = nil, diagnostic: nil)
+        @diagnostic = diagnostic
+        super(msg)
+      end
+    end
+
+    # Raised at DECLARATION time (Component.action -> ParamSchema.compile) when a
+    # param schema names a type symbol that isn't in the registry — a typo like
+    # `params: { count: :interger }`. A stdlib ArgumentError subclass (NOT a
+    # NameError): the mistake is a bad ARGUMENT to `action`, and callers rescue
+    # ArgumentError, not NameError, for a bad-input contract. Loud at class load
+    # (eager loading in production; first constant reference under Zeitwerk dev)
+    # instead of a silent `to_s` at request time.
+    #
+    # Superclass is fully qualified `::ArgumentError`: the phlex gem defines
+    # Phlex::ArgumentError, and a bare `ArgumentError` here resolves LEXICALLY to
+    # that (Phlex::Reactive -> Phlex), coupling us to a Phlex error rather than
+    # the stdlib one an app catches.
+    class UnknownParamType < ::ArgumentError; end
 
     # Purpose string bound into every identity token's signature so a token
     # minted for phlex-reactive can't be replayed against another verifier use.
     IDENTITY_PURPOSE = "phlex-reactive/identity"
 
+    # The current identity-token payload version (issue #111), stamped into every
+    # signed token under the "v" key. It exists so the NEXT breaking shape change
+    # (a rename, per-token expiry, a nonce) can upgrade tokens already in flight
+    # instead of breaking every open page at deploy. A token minted before this
+    # existed carries no "v" — treated as version 0 (today's shape). Bump this and
+    # register a register_token_upgrader(old_version) when you change the shape.
+    TOKEN_VERSION = 1
+
+    # The ActiveSupport::Notifications namespace for the gem's hot-path events
+    # (issue #107): action.phlex_reactive, render.phlex_reactive,
+    # broadcast.phlex_reactive. APM tools (AppSignal, Datadog, Skylight)
+    # auto-subscribe to `*.phlex_reactive` and get component-level visibility.
+    # Payloads carry NAMES/outcome/sizes ONLY — never the token, params, or state.
+    INSTRUMENTATION_NAMESPACE = "phlex_reactive"
+
+    # What a component-aware around_action wrapper sees (issue #112). Frozen: a
+    # wrapper OBSERVES the resolved action — it must not mutate the context to
+    # widen invokability (the token verify, component resolution, default-deny,
+    # and schema coercion have already run and are not negotiable here).
+    #   * component    — the resolved, identity-rebuilt component instance
+    #   * action_name  — the declared action Symbol about to run
+    #   * params       — the SCHEMA-COERCED params (dropped keys already gone)
+    #   * request      — the ActionDispatch::Request (remote_ip, headers, ...)
+    ActionContext = Data.define(:component, :action_name, :params, :request)
+
     class << self
       # The message verifier used to sign/verify component identity tokens.
       # Defaults to a purpose-scoped verifier derived from secret_key_base.
@@ -70,6 +119,162 @@ module Phlex
         @action_path ||= "/reactive/actions"
       end
 
+      # Diagnostic endpoint error bodies + dropped-param logging. When true, an
+      # endpoint failure (400/403/404) carries a plain-text explanation body
+      # (the client already console.errors it) and param coercion warn-logs
+      # every dropped key with its bracketed path and reason. Statuses never
+      # change with the flag, and the endpoint's warn log fires regardless.
+      #
+      # Defaults LAZILY to Rails.env.local? — that's development AND test — so
+      # production stays opaque unless you opt in. The `defined?` guard (not
+      # `||=`) makes an explicit `= false` stick even in dev/test.
+      attr_writer :verbose_errors
+
+      def verbose_errors
+        return @verbose_errors if defined?(@verbose_errors)
+
+        defined?(::Rails.env) && ::Rails.env.local?
+      end
+
+      # Attach the opt-in LogSubscriber (issue #107) so each hot-path event is
+      # debug-logged as one compact line (`[reactive] Counter#increment ok
+      # (3.1ms)`). Default OFF — the events still fire for APMs regardless; this
+      # only controls the gem's own log lines. The engine reads it at boot and
+      # attaches exactly once. Set true in an initializer to see the lines.
+      attr_writer :log_events
+
+      def log_events
+        return @log_events if defined?(@log_events)
+
+        false
+      end
+
+      # Client debug mode (issue #108): the "devtools-lite" lens on the reactive
+      # round trip. When true, reactive_attrs (and so reactive_root) stamps
+      # data-reactive-debug="true" on the root, and the generic controller
+      # console.groups every dispatch — action, param/collected NAMES (never
+      # values), request encoding, HTTP status, the response's stream actions +
+      # targets, whether a token refresh arrived (never the token VALUE), and the
+      # round-trip ms. Default OFF (the initializer template suggests
+      # Rails.env.development?); zero cost when off (one nil-check per dispatch, no
+      # attr, no string building). The `defined?` guard (not `||=`) makes an
+      # explicit `= false` stick even where a truthy default might otherwise apply.
+      attr_writer :debug
+
+      def debug
+        return @debug if defined?(@debug)
+
+        false
+      end
+
+      # Register an app-defined param type (issue #109). The block receives the
+      # raw client value and returns the coerced value — or Phlex::Reactive::
+      # ParamSchema::DROP to reject it (the keyword default then applies, keeping
+      # the drop-don't-fabricate contract). Register in an INITIALIZER: the
+      # registry is frozen after boot (freeze_param_types!), so a runtime
+      # registration raises, and a schema referencing the type is validated at
+      # declaration.
+      #
+      #   # config/initializers/phlex_reactive.rb
+      #   Phlex::Reactive.param_type(:money) do |v|
+      #     /\A\d+(\.\d{1,2})?\z/.match?(v.to_s) ? BigDecimal(v) : Phlex::Reactive::ParamSchema::DROP
+      #   end
+      #   # then: action :charge, params: { amount: :money }
+      def param_type(name, &block)
+        raise ::ArgumentError, "Phlex::Reactive.param_type requires a block" unless block
+
+        if param_types_frozen?
+          raise Error, "Phlex::Reactive.param_type(#{name.inspect}) called after boot — the param-type " \
+                       "registry is frozen once the app is initialized. Register custom param types in an " \
+                       "initializer (config/initializers/phlex_reactive.rb)."
+        end
+
+        param_types[name.to_sym] = block
+      end
+
+      # The param-type registry: Symbol => callable(value) -> coerced | DROP.
+      # Seeded lazily with the built-ins; ParamSchema.compile validates every
+      # declared type symbol against it, and #coerce dispatches through it.
+      def param_types
+        @param_types ||= Phlex::Reactive::ParamSchema.built_in_types.dup
+      end
+
+      # A declared type symbol is known iff it's a registry key. ParamSchema
+      # asks this at compile so an unknown symbol raises loudly at declaration.
+      def param_type?(name)
+        param_types.key?(name.to_sym)
+      end
+
+      # Freeze the registry so no further param_type registration is accepted —
+      # the initializer-only contract. Called by the engine's after_initialize.
+      # Idempotent.
+      def freeze_param_types!
+        param_types.freeze
+        @param_types_frozen = true
+      end
+
+      def param_types_frozen?
+        @param_types_frozen ||= false
+      end
+
+      # Drop the registry back to the built-ins and unfreeze it. For tests that
+      # register a temporary type; never called in production.
+      def reset_param_types!
+        @param_types = Phlex::Reactive::ParamSchema.built_in_types.dup
+        @param_types_frozen = false
+      end
+
+      # Emit an `<event>.phlex_reactive` ActiveSupport::Notifications event around
+      # a block, yielding the mutable payload so a rescue can finalize the outcome
+      # (issue #107). ASN.instrument is cheap when nothing is subscribed (the hot
+      # paths depend on this — proven by the render bench), so this wraps the
+      # render/broadcast/action paths unconditionally. The payload must carry
+      # NAMES/outcome/sizes ONLY — never token/params/state.
+      def instrument(event, payload = {}, &)
+        ::ActiveSupport::Notifications.instrument("#{event}.#{INSTRUMENTATION_NAMESPACE}", payload, &)
+      end
+
+      # Register a COMPONENT-AWARE around_action wrapper (issue #112). The block
+      # is folded into the endpoint BETWEEN with_connection_id and the action's
+      # transaction — so it sees the resolved component instance, the declared
+      # action name, and the coerced params (an ActionContext), and a rejection
+      # NEVER opens a transaction. This is the seam for audit logging,
+      # component-aware rate limiting, and assertions; the base controller
+      # (base_controller_name) remains the seam for HTTP-layer concerns (auth,
+      # CSRF, coarse per-IP rate limiting) that don't need the resolved action.
+      #
+      #   Phlex::Reactive.around_action do |ctx, &action|
+      #     RateLimiter.check!(ctx.request.remote_ip, ctx.action_name) # raise -> 403
+      #     result = action.call
+      #     AuditLog.record!(actor: Current.user, action: ctx.action_name)
+      #     result   # <- REQUIRED: return the continuation's value
+      #   end
+      #
+      # CONTRACT — each wrapper MUST return `action.call`'s value. The endpoint
+      # type-checks the action's return for a Phlex::Reactive::Response; a wrapper
+      # that returns its logger's result instead silently downgrades every reply
+      # to the implicit self-replace. Wrappers nest in registration order with the
+      # LAST-registered outermost. Register in an initializer.
+      def around_action(&block)
+        raise ::ArgumentError, "Phlex::Reactive.around_action requires a block" unless block
+
+        around_actions << block
+      end
+
+      # The registered around_action wrappers, oldest first. The endpoint folds
+      # them so the last-registered runs outermost; an empty stack is the default
+      # hot path (the controller short-circuits with `return yield`).
+      def around_actions
+        @around_actions ||= []
+      end
+
+      # Drop all registered around_action wrappers. For test isolation (the
+      # shipped hook — specs registering a temporary wrapper reset around every
+      # example); never called in production.
+      def reset_around_actions!
+        @around_actions = []
+      end
+
       def verifier
         @verifier ||= default_verifier
       end
@@ -110,6 +315,24 @@ module Phlex
 
       attr_writer :flash_target
 
+      # A user-visible flash rendered on every endpoint rescue path (issue #100).
+      # Default nil = today's behavior (a bare head, or the verbose_errors
+      # plain-text diagnostic). Set a lambda ->(kind) { "message" } (kind is
+      # :tampered/:unknown_class/:not_reactive_class/:forbidden/:not_found) and
+      # the ActionsController ALSO renders a turbo-stream flash into flash_target
+      # — at the SAME status it returns today (statuses never change). Composes
+      # with verbose_errors: the turbo-stream flash wins the response body, the
+      # diagnostic still goes to the log.
+      attr_accessor :error_flash
+
+      # Component class used to render STRING flash content (issue #77).
+      # Instantiated as flash_component.new(level:, content:) and rendered
+      # through the existing render path, replacing the built-in
+      # <div class="reactive-flash reactive-flash--{level}"> wrapper. Default
+      # nil (the built-in wrapper). Phlex component content passed to
+      # reply.flash always renders verbatim and bypasses this.
+      attr_accessor :flash_component
+
       # Render a Phlex component to HTML with a full (off-request) view context.
       # Uses phlex-rails' #render_in against the memoized view context — a direct
       # component.call that skips ActionController's renderer.render machinery
@@ -121,20 +344,24 @@ module Phlex
       end
 
       # A Turbo::Streams::TagBuilder bound to an off-request view context, used
-      # to build standalone streams (e.g. a Response flash append) not tied to a
-      # specific component's id. Cached PER THREAD alongside the context it's
-      # bound to (see off_request_view_context for why per-thread).
-      def flash_builder
+      # to build standalone streams not tied to a specific component's id — a
+      # Response flash append, a reactive_collection row removal, a count
+      # companion update, an also_update companion. Cached PER THREAD alongside
+      # the context it's bound to (see off_request_view_context for why
+      # per-thread). Renamed from flash_builder (issue #113): the builder does
+      # far more than flashes, so the name misled. flash_builder stays a
+      # permanent alias below so the engine's to_prepare and app code keep working.
+      def stream_builder
         off_request_view_context_cache[:builder]
       end
 
       # The off-request view context for the current thread, built once and
-      # reused for both the flash builder and standalone component renders.
+      # reused for both the stream builder and standalone component renders.
       # Cached PER THREAD, not per process: an ActionView context carries mutable
       # output_buffer/view_flow state (render_in's capture swaps it), so sharing
       # one instance across threads can interleave content on a threaded server.
       # Rebuilt when the renderer object changes or the generation is bumped
-      # (reset_flash_builder! / Rails code reload), so a reloaded controller is
+      # (reset_stream_builder! / Rails code reload), so a reloaded controller is
       # never served stale.
       def off_request_view_context
         off_request_view_context_cache[:view_context]
@@ -143,11 +370,19 @@ module Phlex
       # Invalidate the per-thread context + builder for ALL threads by bumping
       # the generation; each thread rebuilds lazily on next use. Registered on
       # Rails' reloader by the engine; also used by specs. Thread-safe (an
-      # integer bump, no shared structure to tear down).
-      def reset_flash_builder!
+      # integer bump, no shared structure to tear down). Renamed from
+      # reset_flash_builder! (issue #113); the old name stays a permanent alias
+      # below so the engine's to_prepare hook keeps working.
+      def reset_stream_builder!
         @off_request_view_context_generation = off_request_view_context_generation + 1
       end
 
+      # Permanent aliases for the pre-#113 names. Kept forever (no deprecation)
+      # so the engine's to_prepare hook and any app code calling the old names
+      # keep working unchanged.
+      alias flash_builder stream_builder
+      alias reset_flash_builder! reset_stream_builder!
+
       def off_request_view_context_generation
         @off_request_view_context_generation ||= 0
       end
@@ -182,14 +417,69 @@ module Phlex
         base_controller_name.constantize
       end
 
-      # Returns the verified payload hash, or nil if the token is invalid.
+      # Returns the verified, version-upgraded payload hash, or nil if the token
+      # is invalid (bad signature/purpose) OR carries a version this code doesn't
+      # understand. The single verify choke point (issue #111): after the
+      # signature check we run upgrade_token so an older-shape payload is migrated
+      # to the current shape before from_identity ever sees it.
       def verify(token)
-        verifier.verified(token, purpose: IDENTITY_PURPOSE)
+        payload = verifier.verified(token, purpose: IDENTITY_PURPOSE)
+        payload && upgrade_token(payload)
       end
 
-      # Signs a payload hash into an identity token.
+      # Signs a payload hash into an identity token, stamping the current
+      # TOKEN_VERSION (issue #111). The "v" key is the ONLY thing added — a
+      # from_identity that ignores unknown keys is unaffected.
       def sign(payload)
-        verifier.generate(payload, purpose: IDENTITY_PURPOSE)
+        verifier.generate(payload.merge("v" => TOKEN_VERSION), purpose: IDENTITY_PURPOSE)
+      end
+
+      # Migrate a verified payload from whatever version it was signed at up to
+      # TOKEN_VERSION (issue #111). Runs the registered upgraders oldest → current,
+      # then stamps the payload to the current version. Contract:
+      #   * no "v"  → version 0 (the shape from before versioning existed). With no
+      #     v0 upgrader registered this is a pure passthrough — introducing
+      #     versioning invalidates NOTHING already in flight.
+      #   * v == current → returned as-is (the hot path — one integer compare).
+      #   * v  > current → nil. A rolled-back deploy verifying a token minted by
+      #     NEWER code must not guess the newer shape; returning nil fails closed
+      #     through the endpoint's existing `|| raise(InvalidToken)` → 400.
+      def upgrade_token(payload)
+        version = payload.fetch("v", 0)
+        # "v" is inside the signed blob, so only our own key could produce a
+        # malformed one — but fail closed rather than 500 on the comparison
+        # (String vs Integer) or silently treat a negative "v" as legacy.
+        return nil unless version.is_a?(::Integer) && version >= 0
+        return payload if version == TOKEN_VERSION
+        return nil if version > TOKEN_VERSION
+
+        upgrade_from(payload, version)
+      end
+
+      # Register an upgrader that rewrites a payload signed at `from_version` into
+      # the shape of `from_version + 1` (issue #111). Register in load order at
+      # boot when you bump TOKEN_VERSION; the block receives the payload hash and
+      # returns the migrated hash (the "v" stamp is applied by upgrade_token, so
+      # the block only reshapes the data). Example, for a future count → n rename:
+      #
+      #   Phlex::Reactive.register_token_upgrader(0) do |payload|
+      #     payload.merge("s" => { "n" => payload.dig("s", "count") })
+      #   end
+      def register_token_upgrader(from_version, &block)
+        raise ::ArgumentError, "register_token_upgrader requires a block" unless block
+
+        token_upgraders[Integer(from_version)] = block
+      end
+
+      # from_version => callable(payload) -> migrated payload. Sparse: an entry
+      # exists only for a version that actually changed shape.
+      def token_upgraders
+        @token_upgraders ||= {}
+      end
+
+      # Drop all registered upgraders. For tests that register a temporary one.
+      def reset_token_upgraders!
+        @token_upgraders = {}
       end
 
       # The acting client's SSE connection id during an action, or nil. Set by
@@ -265,6 +555,27 @@ module Phlex
         ::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger)
       end
 
+      # Walk the upgrader chain from `version` up to TOKEN_VERSION, applying each
+      # registered upgrader in turn (issue #111). A gap in the chain (a version
+      # bumped with no shape change, so no upgrader registered) is a no-op step —
+      # the payload passes through unchanged to the next version. Only stamp the
+      # current "v" if an upgrader ACTUALLY reshaped the payload: a versionless
+      # (v0) token with no upgraders registered — today's case — is returned
+      # byte-identical, so introducing versioning invalidates nothing in flight.
+      # Runs only for a genuinely old token (the v == current hot path already
+      # returned in upgrade_token), so this is off the render path.
+      def upgrade_from(payload, version)
+        upgraded = false
+        version.upto(TOKEN_VERSION - 1) do
+          upgrader = token_upgraders[it]
+          next unless upgrader
+
+          payload = upgrader.call(payload)
+          upgraded = true
+        end
+        upgraded ? payload.merge("v" => TOKEN_VERSION) : payload
+      end
+
       def default_verifier
         unless defined?(::Rails) && ::Rails.application
           raise Error, "Phlex::Reactive.verifier is unset and Rails.application is unavailable; " \
@@ -285,6 +596,9 @@ loader.tag = "phlex-reactive"
 # (lib/phlex/reactive/foo.rb -> Phlex::Reactive::Foo).
 lib = File.expand_path("..", __dir__)
 loader.push_dir(lib)
+# js.rb defines JS and component/dsl.rb defines Component::DSL (acronyms), not
+# the default-inflected `Js`/`Dsl`.
+loader.inflector.inflect("js" => "JS", "dsl" => "DSL")
 # The gem-name shim (`require "phlex-reactive"`) is a plain require, not a
 # managed file.
 loader.ignore("#{lib}/phlex-reactive.rb")
@@ -296,6 +610,11 @@ loader.ignore("#{lib}/phlex/reactive/version.rb")
 # (generators/phlex/reactive/... defining Phlex::Reactive::Generators::...)
 # deliberately doesn't follow Zeitwerk's rules, so the loader must ignore them.
 loader.ignore("#{lib}/generators")
+# The RSpec matchers file (issue #110) defines RSpec::Matchers, not a
+# Phlex::Reactive::TestHelpers::Matchers constant, so it doesn't follow
+# Zeitwerk's naming — test_helpers.rb requires it explicitly (only when RSpec is
+# present), and the loader must ignore it.
+loader.ignore("#{lib}/phlex/reactive/test_helpers/matchers.rb")
 # The engine is required explicitly below (only when Rails is present) and must
 # not be eager-loaded before that.
 loader.do_not_eager_load("#{__dir__}/reactive/engine.rb")

data/lib/tasks/phlex_reactive.rake

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Rails engines auto-load rake tasks under lib/tasks — no engine.rb change is
+# needed for `bin/rails phlex_reactive:doctor` to appear in the host app.
+namespace :phlex_reactive do
+  desc "Validate the phlex-reactive install (route, Stimulus, verifier, components) — issue #106"
+  task doctor: :environment do
+    # Doctor.run eager-loads so the component registry is populated, prints the
+    # ✓/✗/? report (with a fix per failure), and returns false if any check
+    # FAILED (advisory `?` lines don't count) — abort so CI / a setup script can
+    # gate on `bin/rails phlex_reactive:doctor`.
+    abort unless Phlex::Reactive::Doctor.run
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: phlex-reactive
 version: !ruby/object:Gem::Version
-  version: 0.4.8
+  version: 0.9.1
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -118,8 +118,14 @@ files:
 - README.md
 - app/controllers/phlex/reactive/actions_controller.rb
 - app/javascript/phlex/reactive/compute.js
+- app/javascript/phlex/reactive/compute.min.js
+- app/javascript/phlex/reactive/compute.min.js.map
 - app/javascript/phlex/reactive/confirm.js
+- app/javascript/phlex/reactive/confirm.min.js
+- app/javascript/phlex/reactive/confirm.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
 - lib/generators/phlex/reactive/component/USAGE
 - lib/generators/phlex/reactive/component/component_generator.rb
 - lib/generators/phlex/reactive/component/templates/component.rb.erb
@@ -130,11 +136,23 @@ files:
 - lib/phlex-reactive.rb
 - lib/phlex/reactive.rb
 - lib/phlex/reactive/component.rb
+- lib/phlex/reactive/component/dsl.rb
+- lib/phlex/reactive/component/helpers.rb
+- lib/phlex/reactive/component/identity.rb
+- lib/phlex/reactive/component/registry.rb
+- lib/phlex/reactive/doctor.rb
 - lib/phlex/reactive/engine.rb
+- lib/phlex/reactive/js.rb
+- lib/phlex/reactive/log_subscriber.rb
+- lib/phlex/reactive/param_schema.rb
 - lib/phlex/reactive/reply.rb
 - lib/phlex/reactive/response.rb
+- lib/phlex/reactive/stream.rb
 - lib/phlex/reactive/streamable.rb
+- lib/phlex/reactive/test_helpers.rb
+- lib/phlex/reactive/test_helpers/matchers.rb
 - lib/phlex/reactive/version.rb
+- lib/tasks/phlex_reactive.rake
 homepage: https://github.com/mhenrixon/phlex-reactive
 licenses:
 - MIT