ruact 0.0.5 → 0.0.6

data/lib/ruact/doctor.rb

@@ -7,7 +7,7 @@ module Ruact
   # Runs a suite of installation health checks and prints ✓/✗ per check.
   # Extracted from the ruact:doctor Rake task for direct testability (FR27).
   class Doctor
-    CHECKS = %i[manifest vite controller layout streaming legacy_constant].freeze
+    CHECKS = %i[manifest vite controller layout streaming legacy_constant serialize_only flight_middleware].freeze
     # Built via Array#join so the gem-CI `name-propagation` guard does not
     # match these literals against itself (Story 5.1 review F4 — the doctor
     # file participates in the guard with no exclusion).
@@ -17,7 +17,61 @@ module Ruact
     LEGACY_SCAN_GLOBS = ["config/initializers/**/*.rb", "app/**/*.rb"].freeze
     RENAME_DOC_URL = "https://github.com/luizcg/ruact/blob/main/CHANGELOG.md#renamed"
 
-    # Runs all checks, prints results, returns true if all pass.
+    # --- Story 13.1: serialize-only invariant tripwire (FR97) ---------------
+    #
+    # ruact EMITS React Flight (`text/x-component`) but must never DESERIALIZE
+    # externally-supplied Flight into live Ruby objects — that keeps it outside
+    # the React2Shell / CVE-2025-55182 class (a Flight-deserialization RCE). See
+    # the ADR addendum in docs/internal/decisions/server-functions-api.md.
+    #
+    # The signal literals are assembled from fragments via Array#join so this
+    # file does NOT itself contain the matched strings (mirrors the LEGACY_CONST
+    # F4 lesson). `doctor.rb` is also excluded from the scan as defense in depth.
+    # Only structural inbound-deserialization signals are used; the raw
+    # `text/x-component` token is deliberately NOT a signal because the gem
+    # legitimately EMITS that media type (controller.rb / server.rb) — matching
+    # it would false-fail the current, invariant-holding tree.
+    DESERIALIZE_SIGNALS = [
+      # a `Deserializer` constant reference (FlightDeserializer, Flight::Deserializer, …);
+      # matched as a substring so both the joined and namespaced forms trip it
+      /#{%w[Deser ializer].join}/,
+      # methods that turn inbound Flight into Ruby objects
+      /\b#{%w[deserialize flight].join('_')}\b/,
+      /\b#{%w[from flight].join('_')}\b/,
+      /\b#{%w[parse flight].join('_')}\b/,
+      /\b#{%w[decode flight].join('_')}\b/,
+      # React Flight reader entry points invoked from Ruby (NOT createFromFlightPayload,
+      # which is the client/browser deserializing the server's own trusted payload)
+      /\b#{%w[create From].join}(?:NodeStream|ReadableStream|Fetch)\b/
+    ].freeze
+    DESERIALIZE_SIGNAL_RE = Regexp.union(DESERIALIZE_SIGNALS)
+    # A line carrying this annotation is a deliberate, reviewed deserializer and
+    # is treated as guarded (the check is a guard, not a blanket ban).
+    ALLOW_FLIGHT_DESERIALIZATION = ["# ruact:allow", "flight", "deserialization"].join("-")
+    # Exclude THIS file by its exact path (not basename) — its comments contain
+    # the literal `Deserializer` example, so it must not match its own scan; but
+    # a differently-located future file also named `doctor.rb` must still be
+    # scanned (review finding R1 — basename exclusion was too broad).
+    DOCTOR_FILE = File.expand_path(__FILE__)
+    SERIALIZE_ONLY_DOC = "docs/internal/decisions/server-functions-api.md (serialize-only invariant, FR97)"
+
+    # Response-transforming middleware that can mutate/recompress a streamed
+    # `text/x-component` Flight body and break the wire contract (React-on-Rails
+    # ops lesson). Matched by class name so the check needs no hard dependency.
+    RESPONSE_TRANSFORMING_MIDDLEWARE = %w[Rack::Deflater].freeze
+
+    # Statuses that do NOT fail the run. Anything else (including a malformed /
+    # future status) is treated as a failure (review finding R1).
+    SUCCESS_STATUSES = %i[pass warn].freeze
+
+    # @param serialize_only_root [String] directory whose `**/*.rb` is scanned
+    #   for the serialize-only tripwire. Defaults to the gem's own `lib/`;
+    #   injectable so specs can point it at a fixture tree.
+    def initialize(serialize_only_root: File.join(Ruact.gem_path, "lib"))
+      @serialize_only_root = serialize_only_root
+    end
+
+    # Runs all checks, prints results, returns true if none FAIL.
     def self.run
       new.run
     end
@@ -26,7 +80,10 @@ module Ruact
       puts "[ruact] Health check"
       results = CHECKS.map { |check| send(:"check_#{check}") }
       results.each { |status, message| puts format_result(status, message) }
-      passed = results.all? { |status, _| status == :pass }
+      # A :warn must NOT fail the run (Story 13.1 AC3); only :pass / :warn are
+      # success. An unexpected status (rendered `✗`) fails loudly rather than
+      # being silently treated as a pass (review finding R1).
+      passed = results.all? { |status, _| SUCCESS_STATUSES.include?(status) }
       puts "Run rails generate ruact:install to fix configuration issues" unless passed
       passed
     end
@@ -96,6 +153,74 @@ module Ruact
        "See #{RENAME_DOC_URL}."]
     end
 
+    # Story 13.1 (AC2) — fails when ruact's OWN Ruby source introduces an
+    # inbound Flight-deserialization entry point that is not explicitly
+    # annotated `# ruact:allow-flight-deserialization <reason>`. Passes silently
+    # when none exists (the current tree). Scans `@serialize_only_root/**/*.rb`,
+    # excluding this file and the generators' client-side templates.
+    def check_serialize_only
+      offenses = Dir[File.join(@serialize_only_root, "**", "*.rb")].flat_map do |file|
+        next [] if File.expand_path(file) == DOCTOR_FILE
+        next [] if file.match?(%r{/generators/.+/templates/})
+
+        File.foreach(file).with_index(1).filter_map do |line, lineno|
+          next unless DESERIALIZE_SIGNAL_RE.match?(line)
+          next if line.include?(ALLOW_FLIGHT_DESERIALIZATION)
+
+          "#{file}:#{lineno}"
+        end
+      end
+
+      if offenses.empty?
+        return [:pass, "Serialize-only invariant holds — no inbound Flight deserializer in ruact's Ruby source"]
+      end
+
+      [:fail,
+       "Inbound Flight deserializer entry point found in #{offenses.length} location(s) " \
+       "(first: #{offenses.first}). ruact is serialize-only: it may emit `text/x-component` " \
+       "but must never deserialize externally-supplied Flight into live Ruby objects " \
+       "(React2Shell / CVE-2025-55182 class). Remove it, or — if deliberate and reviewed — " \
+       "annotate the line with `#{ALLOW_FLIGHT_DESERIALIZATION} <reason>`. See #{SERIALIZE_ONLY_DOC}."]
+    end
+
+    # Story 13.1 (AC3) — WARNS (never fails) when a response-transforming
+    # middleware is mounted in the app's stack, since it may recompress/mutate a
+    # streamed `text/x-component` Flight body and break the wire contract.
+    def check_flight_middleware
+      stack = flight_middleware_stack
+      return [:pass, "No response-transforming middleware on the Flight wire path"] if stack.nil?
+
+      present = stack.filter_map { |mw| middleware_name(mw) }
+                     .select { |name| RESPONSE_TRANSFORMING_MIDDLEWARE.include?(name) }
+                     .uniq
+      return [:pass, "No response-transforming middleware on the Flight wire path"] if present.empty?
+
+      [:warn,
+       "#{present.join(', ')} is mounted and may transform `text/x-component` (Flight) responses, " \
+       "breaking the wire contract / streaming. Exclude Flight responses from compression " \
+       "(don't compress `text/x-component`) or mount it so it does not wrap the Flight routes."]
+    end
+
+    # Returns the app middleware stack to scan, or nil when unavailable (no
+    # Rails application present — e.g. the non-Rails / full-stub edge context).
+    # At real `rails ruact:doctor` time the `:environment` task has booted the
+    # app, so `app.middleware` is the enumerable `ActionDispatch::MiddlewareStack`.
+    # Before `initialize!` it is a `Rails::Configuration::MiddlewareStackProxy`
+    # (not enumerable) — skip it rather than crash on `filter_map`.
+    def flight_middleware_stack
+      return nil unless defined?(Rails) && Rails.respond_to?(:application)
+
+      app = Rails.application
+      return nil unless app.respond_to?(:middleware)
+
+      stack = app.middleware
+      stack.respond_to?(:each) ? stack : nil
+    end
+
+    def middleware_name(middleware)
+      middleware.respond_to?(:name) ? middleware.name : middleware.to_s
+    end
+
     def streaming_server_hint
       return "Puma"      if defined?(::Puma)
       return "Unicorn"   if defined?(::Unicorn)
@@ -110,7 +235,11 @@ module Ruact
     end
 
     def format_result(status, message)
-      status == :pass ? "✓ #{message}" : "✗ #{message}"
+      case status
+      when :pass then "✓ #{message}"
+      when :warn then "⚠ #{message}"
+      else            "✗ #{message}"
+      end
     end
   end
 end

data/lib/ruact/erb_preprocessor.rb

@@ -35,11 +35,22 @@ module Ruact
 
     # Transform ERB source, replacing component tags with ERB placeholders.
     # Returns the transformed source string.
-    def self.transform(source)
-      new.transform(source)
+    #
+    # +identifier+ is the template path (forwarded by {ErbPreprocessorHook} as
+    # +template.identifier+) so a Story 13.5 contract violation can name the
+    # call site's file:line. +registry+ is the component contract source — an
+    # injectable seam (Story 7.1 explicit-context grain); it defaults to the
+    # process-loaded {Ruact.manifest}. Pass +registry: nil+ (or a stub) in
+    # specs to control contract lookup; +nil+ forces fail-open (no validation).
+    def self.transform(source, identifier: nil, registry: :default)
+      new.transform(source, identifier: identifier, registry: registry)
     end
 
-    def transform(source)
+    def transform(source, identifier: nil, registry: :default)
+      # NOTE: +registry+ stays the +:default+ sentinel here. It is resolved to
+      # +Ruact.manifest+ LAZILY, only inside the component-tag block below — a
+      # source with no PascalCase tags must touch the registry not at all
+      # (AC2/AC6 fast-path invariant).
       # Step 1: transform <Suspense> paired tags into <ruact-suspense> HTML elements.
       # This runs before the general component regex so Suspense isn't treated as a component.
       result = source
@@ -47,7 +58,11 @@ module Ruact
                  attrs    = ::Regexp.last_match(1)
                  fallback = extract_string_attr(attrs, "fallback") || ""
                  escaped  = fallback.gsub('"', "&quot;")
-                 %(<ruact-suspense data-ruact-fallback="#{escaped}">)
+                 # Optional `delay="2.5"` — the server-side wait (seconds) before
+                 # the deferred chunk streams. Forwarded to SuspenseElement#delay.
+                 delay      = extract_string_attr(attrs, "delay")
+                 delay_attr = delay ? %( data-ruact-delay="#{delay.gsub('"', '&quot;')}") : ""
+                 %(<ruact-suspense data-ruact-fallback="#{escaped}"#{delay_attr}>)
                end
         .gsub(SUSPENSE_CLOSE_RE, "</ruact-suspense>")
 
@@ -59,9 +74,17 @@ module Ruact
         line           = result[0...match_start].count("\n") + 1
 
         begin
-          props_ruby = parse_props(attrs_string)
+          registry = Ruact.manifest if registry == :default # lazy — only when a tag exists
+          pairs = parse_prop_pairs(attrs_string)
+          validate_contract(registry, component_name, pairs.map(&:first),
+                            at: { file: identifier, line: line, snippet: match.strip })
+          props_ruby = pairs.map { |name, expr| "#{name.inspect} => #{expr}" }.join(", ")
           props_hash = props_ruby.empty? ? "{}" : "{ #{props_ruby} }"
           %(<%= __ruact_component__(#{component_name.inspect}, #{props_hash}) %>)
+        rescue ComponentContractError
+          # Already carries file:line + offending prop + suggestion — re-raise
+          # AS-IS (do NOT append the generic "at line N: snippet" tail).
+          raise
         rescue PreprocessorError => e
           raise PreprocessorError, "#{e.message} at line #{line}: #{match.strip}"
         end
@@ -77,11 +100,41 @@ module Ruact
       m&.[](1)
     end
 
-    # Parses the attributes string of a component tag and returns a Ruby
-    # fragment representing a Hash literal, e.g.:
-    #   "postId" => @post.id, "initialCount" => 5
-    def parse_props(attrs_string)
-      return "" if attrs_string.empty?
+    # Story 13.5 — run the opt-in contract check for +component_name+ against
+    # the parsed call-site prop +names+. Looks the contract up through the
+    # injected +registry+ seam and SKIPS ENTIRELY when there is none (no
+    # registry, registry without +contract_for+, or no contract for this
+    # component) — that is the AC2/AC6 fail-open path that keeps a contract-less
+    # component byte-identical. Invoked ONLY inside the component-tag block, so
+    # the no-tag fast path never reads the registry.
+    def validate_contract(registry, component_name, names, at:)
+      return unless registry.respond_to?(:contract_for)
+
+      contract = registry.contract_for(component_name, controller_path: controller_path_from(at[:file]))
+      return if contract.nil?
+
+      ComponentContract.validate(
+        component_name: component_name, prop_names: names, contract: contract, at: at
+      )
+    end
+
+    # Best-effort controller_path from a template identifier so a co-located
+    # component's contract resolves (e.g. ".../app/views/posts/show.html.erb"
+    # → "posts"). A wrong/absent guess is harmless: {ClientManifest#resolve_key}
+    # falls back to the shared PascalCase key.
+    def controller_path_from(identifier)
+      return nil unless identifier
+
+      m = identifier.to_s.match(%r{app/views/(.+)/[^/]+\z})
+      m && m[1]
+    end
+
+    # Parses the attributes string of a component tag into ordered
+    # +[name, ruby_expr]+ pairs, e.g. [["postId", "@post.id"], ["count", "5"]].
+    # Honors nested braces in values (via {#extract_braced_expr}). The names
+    # feed the Story 13.5 contract check; the pairs render the props Hash.
+    def parse_prop_pairs(attrs_string)
+      return [] if attrs_string.empty?
 
       pairs = []
       remaining = attrs_string.dup
@@ -91,13 +144,13 @@ module Ruact
         # Find the matching closing brace, respecting nesting
         value_start = m.end(0)
         value_expr  = extract_braced_expr(remaining, value_start)
-        pairs << "#{prop_name.inspect} => #{value_expr}"
+        pairs << [prop_name, value_expr]
         # Advance past this prop
         remaining = remaining[(value_start + value_expr.length + 1)..] # +1 for closing }
         break if remaining.nil?
       end
 
-      pairs.join(", ")
+      pairs
     end
 
     # Given a string and a start position (just after the opening '{'),

data/lib/ruact/erb_preprocessor_hook.rb

@@ -14,7 +14,10 @@ module Ruact
     # Called by ActionView for every ERB template. +source+ is the raw ERB
     # text; the return value is Ruby code that ActionView will eval.
     def call(template, source)
-      super(template, ErbPreprocessor.transform(source))
+      # Story 13.5 — forward +template.identifier+ (the template file path) so a
+      # component-contract violation can name the call site's file:line. The
+      # contract registry defaults to the process-loaded +Ruact.manifest+.
+      super(template, ErbPreprocessor.transform(source, identifier: template.identifier))
     end
   end
 end

data/lib/ruact/errors.rb

@@ -12,6 +12,16 @@ module Ruact
   # Raised when the ERB preprocessor encounters a malformed component tag.
   class PreprocessorError < Error; end
 
+  # Story 13.5 (FR100) — raised by {Ruact::ComponentContract} at ERB
+  # preprocess-time when a `<Component .../>` call site violates the component's
+  # opt-in contract: a missing required prop/slot or an unknown prop name.
+  # Subclasses {PreprocessorError} so it flows through the same dev error
+  # overlay (NFR30 lineage) and the hook treats it uniformly — but the distinct
+  # class lets the preprocessor re-raise it AS-IS (its message already carries
+  # file:line + the offending prop + a "did you mean?" suggestion) instead of
+  # re-wrapping it with the generic "at line N: snippet" tail.
+  class ComponentContractError < PreprocessorError; end
+
   # Raised when application code attempts to mutate Ruact::Configuration outside
   # of a Ruact.configure block. The configuration is frozen after initialization
   # to prevent runtime drift; see Story 7.3 for the rationale and the decision
@@ -26,43 +36,6 @@ module Ruact
   # buried under a Nokogiri stack. See Story 7.4 for the rationale.
   class HtmlConverterError < Error; end
 
-  # Story 8.3 — raised by a standalone server-action block (a module that
-  # `extend`s {Ruact::ServerAction}) when its body invokes
-  # {Ruact::ServerFunctions::StandaloneContext#current_user} but no
-  # {Ruact::Configuration#current_user_resolver} has been configured. The
-  # message names both worked examples (Devise + hand-rolled session) so
-  # the developer can wire the resolver without leaving the stack trace.
-  class CurrentUserNotConfiguredError < Error
-    DEFAULT_MESSAGE = "Ruact.current_user requires Ruact.config.current_user_resolver to be set. " \
-                      "Example (Devise): Ruact.configure { |c| c.current_user_resolver = ->(env) { env['warden']&.user } }. " \
-                      "Example (hand-rolled session): Ruact.configure { |c| c.current_user_resolver = " \
-                      "->(env) { User.find_by(id: env['rack.session'][:user_id]) } }."
-
-    def initialize(message = DEFAULT_MESSAGE)
-      super
-    end
-  end
-
-  # Story 8.3 — raised inside a standalone server-action block to surface a
-  # non-2xx response without calling `render` (which the StandaloneContext
-  # does not expose). The endpoint dispatcher rescues this exception class
-  # and renders `status` + `body` verbatim, mirroring how a controller-hosted
-  # action would call `render(json: ..., status: ...)`.
-  class ActionError < Error
-    attr_reader :status, :body
-
-    # @param status [Symbol, Integer] HTTP status (e.g. :unprocessable_entity, 422).
-    # @param body [Object] the response payload. Hash/Array/scalar values are
-    #   rendered as JSON; nil renders an empty body.
-    # @param message [String] optional message; defaults to "ruact action error
-    #   (status=<status>)" so the exception is still legible in logs.
-    def initialize(status:, body: nil, message: nil)
-      @status = status
-      @body = body
-      super(message || "ruact action error (status=#{status.inspect})")
-    end
-  end
-
   # Story 9.5 (FR88) — raised by the query dispatch controller when a
   # `useQuery` request's parameters violate the kwargs allowlist: a complex
   # value (array / object) where only `string | number | boolean | null` is
@@ -74,14 +47,27 @@ module Ruact
   # fix the call site without reading the server source.
   class BadRequestError < Error; end
 
-  # Story 8.5 — raised by `EndpointController#__ruact_enforce_upload_limit!`
-  # when an inbound multipart / urlencoded request's `Content-Length` exceeds
+  # Story 13.2 (FR96) — raised by `Ruact.locate_signed` when a SignedGlobalID
+  # token fails verification: a tampered signature, an expired token, or a token
+  # scoped to a different `for:` purpose (`GlobalID::Locator.locate_signed`
+  # returns `nil`). Inherits from `Ruact::Error` so the Story 8.4
+  # `rescue_from StandardError` chain catches it cleanly; `__ruact_status_for`
+  # maps it to HTTP 400 (Bad Request) — a forged/expired reference is an
+  # invalid credential the client supplied, NOT a missing record. This keeps
+  # `ActiveRecord::RecordNotFound` from leaking and never reveals whether the
+  # target record exists (verification fails before any DB lookup). A *valid*
+  # token whose record was since deleted is NOT this error — the underlying
+  # finder (`ActiveRecord::RecordNotFound`) propagates and is the host's normal
+  # not-found concern, exactly as a raw `Model.find` would be.
+  class InvalidSignedGlobalIDError < Error; end
+
+  # Story 8.5 — raised by the `Ruact::Server` upload guard when an inbound
+  # multipart / urlencoded request's `Content-Length` exceeds
   # `Ruact.config.max_upload_bytes`. The exception inherits from
-  # `Ruact::Error` so the Story 8.4 `rescue_from StandardError` chain on
-  # `EndpointController` catches it cleanly; the endpoint controller's
-  # `__ruact_status_for` maps it to HTTP 413, and `ErrorPayload.build`
-  # extracts the `received_bytes` / `limit_bytes` pair into a dev-only
-  # `upload_limit` block alongside the four baseline keys.
+  # `Ruact::Error` so the Story 8.4 `rescue_from StandardError` chain catches
+  # it cleanly; `__ruact_status_for` maps it to HTTP 413, and
+  # `ErrorPayload.build` extracts the `received_bytes` / `limit_bytes` pair
+  # into a dev-only `upload_limit` block alongside the four baseline keys.
   #
   # The pair is exposed as `attr_reader` so the structured payload (and host
   # log lines) can show both numbers without re-parsing the message string.

data/lib/ruact/html_converter.rb

@@ -201,7 +201,28 @@ module Ruact
       child_nodes = convert_children(node)
       children = child_nodes.length == 1 ? child_nodes.first : child_nodes
 
-      Flight::SuspenseElement.new(fallback: fallback, children: children)
+      # Optional `delay="2.5"` from the ERB → SuspenseElement#delay (the
+      # server-side wait, in seconds, before the deferred chunk streams). When
+      # absent, blank, unparseable, or non-finite, SuspenseElement falls back to
+      # its default.
+      delay_attr = node["data-ruact-delay"]
+      delay = begin
+        if delay_attr && !delay_attr.to_s.strip.empty?
+          # A string overflow like "1e309" parses to Infinity (Float() does not
+          # raise) — guard finiteness so a non-finite delay can't reach the
+          # renderer's sleep(delay) and raise RangeError.
+          parsed = Float(delay_attr)
+          parsed.finite? ? parsed : nil
+        end
+      rescue ArgumentError, TypeError
+        nil
+      end
+
+      if delay
+        Flight::SuspenseElement.new(fallback: fallback, children: children, delay: delay)
+      else
+        Flight::SuspenseElement.new(fallback: fallback, children: children)
+      end
     end
 
     def convert_children(node)