ruact 0.0.2 → 0.0.4

data/lib/ruact/errors.rb

@@ -11,4 +11,104 @@ module Ruact
 
   # Raised when the ERB preprocessor encounters a malformed component tag.
   class PreprocessorError < Error; 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
+  # note for guidance on when re-configuration at runtime is appropriate.
+  class ConfigurationError < Error; end
+
+  # Raised by `Ruact::HtmlConverter.convert` when its input is not a `String`
+  # (the only accepted shape). Catches the most common upstream bug — an ERB
+  # template, partial, or render path that returned `nil` or a non-String value
+  # — at the boundary, before Nokogiri is invoked, so the failing file:line and
+  # the expected shape are visible at the top of the backtrace instead of
+  # 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
+  # accepted, a missing required keyword, or an unknown parameter that matches
+  # no declared kwarg. Inherits from `Ruact::Error` so the Story 8.4
+  # `rescue_from StandardError` chain on the dispatch controller catches it
+  # cleanly; `__ruact_status_for` maps it to HTTP 400 (Bad Request). The
+  # message names the offending key and the allowlist so the React dev can
+  # 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
+  # `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.
+  #
+  # 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.
+  # Numbers report the WIRE `Content-Length` (which includes multipart
+  # boundary overhead — a 9.5 MB file uploaded via multipart will report a
+  # `received_bytes` slightly larger than the file size), not the parsed
+  # file size — that's what the guard checks, and reporting the same number
+  # avoids "why does the error say 9.7 MB when my file is 9.5 MB?" surprise.
+  #
+  # @example Construction shape (matches how the guard raises)
+  #   raise Ruact::UploadTooLargeError.new(
+  #     received_bytes: request.content_length,
+  #     limit_bytes:    Ruact.config.max_upload_bytes
+  #   )
+  class UploadTooLargeError < Error
+    attr_reader :received_bytes, :limit_bytes
+
+    # @param received_bytes [Integer] wire `Content-Length` of the rejected request.
+    # @param limit_bytes [Integer] configured `Ruact.config.max_upload_bytes` at reject time.
+    # @param message [String] optional override; defaults to a string that
+    #   names both numbers so the exception is legible without consulting
+    #   the attr_readers.
+    def initialize(received_bytes:, limit_bytes:, message: nil)
+      @received_bytes = received_bytes
+      @limit_bytes = limit_bytes
+      super(message || "Upload exceeded the configured size limit " \
+                       "(received_bytes=#{received_bytes}, limit_bytes=#{limit_bytes})")
+    end
+  end
 end

data/lib/ruact/flight/serializer.rb

@@ -166,7 +166,7 @@ module Ruact
       # --- Serializable (explicit opt-in, no warning) ---
 
       def serialize_serializable(value)
-        serialize_model(value.rsc_serialize)
+        serialize_model(value.ruact_serialize)
       end
 
       # --- as_json fallback (strict_serialization: false only) ---
@@ -182,7 +182,7 @@ module Ruact
         if data.equal?(value)
           raise Ruact::SerializationError,
                 "#{value.class.name}#as_json returned self — would cause infinite recursion. " \
-                "Include Ruact::Serializable and declare rsc_props instead"
+                "Include Ruact::Serializable and declare ruact_props instead"
         end
 
         attr_names = data.is_a?(Hash) ? data.keys.join(", ") : ""

data/lib/ruact/html_converter.rb

@@ -8,9 +8,10 @@ module Ruact
   # Rules:
   # - HTML attributes → React equivalents (class→className, for→htmlFor, etc.)
   # - data-react-key="x" → becomes the React key on the element
-  # - HTML comments matching __RSC_N__ tokens → replaced by client component refs
+  # - HTML comments matching __RUACT_N__ tokens → replaced by client component refs
   # - Text nodes → plain Ruby strings
   # - Multiple root nodes → wrapped in a Fragment (array)
+  # rubocop:disable Metrics/ClassLength
   class HtmlConverter
     # HTML attribute → React prop name mapping
     HTML_TO_REACT = {
@@ -34,8 +35,18 @@ module Ruact
       "spellcheck" => "spellCheck"
     }.freeze
 
+    # Tags whose `value` attribute maps to React's `defaultValue` (uncontrolled).
+    DEFAULT_VALUE_TAGS = %w[textarea select].freeze
+
+    # <input type=...> values for which `value` keeps its name in React (button-like inputs).
+    INPUT_BUTTON_TYPES = %w[submit reset button image].freeze
+
     # Convert an HTML string into a ReactElement tree.
     # component_registry is an array of { token:, name:, ref: ClientReference, props: Hash }
+    #
+    # Raises +Ruact::HtmlConverterError+ if +html+ is not a +String+. The
+    # validation runs before Nokogiri is invoked, so the caller's file:line
+    # appears at the top of the backtrace rather than Nokogiri internals.
     def self.convert(html, component_registry = [])
       new(component_registry).convert(html)
     end
@@ -44,7 +55,14 @@ module Ruact
       @registry = component_registry
     end
 
+    # Convert an HTML string into a ReactElement tree (instance form).
+    #
+    # Raises +Ruact::HtmlConverterError+ if +html+ is not a +String+. The
+    # validation runs before Nokogiri is invoked, so the caller's file:line
+    # appears at the top of the backtrace rather than Nokogiri internals.
     def convert(html)
+      validate_html_input!(html)
+
       # Wrap in a fragment container so Nokogiri gives us a consistent root.
       # Use HTML4 fragment parser (universally available, no libgumbo needed).
       doc = Nokogiri::HTML::DocumentFragment.parse(html)
@@ -59,6 +77,80 @@ module Ruact
 
     private
 
+    # Story 7.4: validate the +html+ input at the boundary so that a stray nil
+    # or non-String value produces a clear ruact-named error pointing at the
+    # caller's file:line instead of a Nokogiri stack trace.
+    #
+    # +String === html+ is used instead of +html.is_a?(String)+ because it
+    # delegates to +Module#===+ on +String+ rather than calling a method on
+    # +html+. This means even +BasicObject+ instances (which lack +is_a?+,
+    # +kind_of?+, and +.class+) raise +Ruact::HtmlConverterError+ here instead
+    # of +NoMethodError+. The message-building helper rescues every method
+    # call on +html+ for the same reason.
+    def validate_html_input!(html)
+      return if String === html # rubocop:disable Style/CaseEquality
+
+      # Walk the stack until we leave html_converter.rb — handles both the
+      # class form (HtmlConverter.convert → instance #convert) and the
+      # instance form, so the message always points at the application caller.
+      gem_file = __FILE__
+      stack = caller_locations(1, 10) || []
+      app_frames = stack.drop_while { |loc| loc.path == gem_file }
+      location = app_frames.first || stack.first
+
+      message = build_input_error_message(html, location)
+      app_backtrace = app_frames.map { |loc| "#{loc.path}:#{loc.lineno}:in `#{loc.label}'" }
+      app_backtrace = caller(1) if app_backtrace.empty?
+      raise Ruact::HtmlConverterError, message, app_backtrace
+    end
+
+    def build_input_error_message(value, location)
+      called_from = "Called from: #{location.path}:#{location.lineno}"
+      doc_pointer = "See HtmlConverter.convert documentation for the canonical contract."
+
+      # +nil.equal?(value)+ instead of +value.nil?+: BasicObject has no
+      # +nil?+ method, so identity comparison through nil's side is the
+      # only safe path.
+      if nil.equal?(value)
+        <<~MSG.strip
+          ruact: HtmlConverter.convert received nil; expected a String of HTML.
+            Most likely cause: an ERB template, partial, or render path returned nil instead of an HTML string. Check the call site for a missing yield, an empty respond_to branch, or a partial that returned nil.
+            #{called_from}
+            #{doc_pointer}
+        MSG
+      else
+        klass_name = safe_class_name(value)
+        preview = safe_inspect_preview(value)
+        <<~MSG.strip
+          ruact: HtmlConverter.convert expected a String of HTML; got #{klass_name}.
+            Received: #{preview}
+            #{called_from}
+            #{doc_pointer}
+        MSG
+      end
+    end
+
+    # Rescue around +.class+ so +BasicObject+ instances (and anything else
+    # that overrides or lacks +.class+) still produce a readable message.
+    def safe_class_name(value)
+      value.class.to_s
+    rescue StandardError
+      "an unknown object"
+    end
+
+    # Truncate +inspect+ to 80 chars (preview window). Rescue any exception
+    # raised by a hostile +inspect+ so the validation never propagates a
+    # third-party error class instead of +Ruact::HtmlConverterError+.
+    def safe_inspect_preview(value)
+      raw = value.inspect
+      raw = raw.to_s
+      truncated = raw[0, 80]
+      truncated += "..." if raw.length > 80
+      truncated
+    rescue StandardError
+      "<inspect raised>"
+    end
+
     def ignorable?(node)
       node.text? && node.text.strip.empty?
     end
@@ -70,7 +162,7 @@ module Ruact
         text.strip.empty? ? nil : text
 
       when Nokogiri::XML::Node::COMMENT_NODE
-        # Check if this is an RSC component placeholder
+        # Check if this is a Ruact component placeholder
         token = node.content.strip
         entry = @registry.find { |c| c[:token] == token }
         return nil unless entry
@@ -89,48 +181,55 @@ module Ruact
 
     def convert_element(node)
       tag = node.name.downcase
+      return convert_suspense_element(node) if tag == "ruact-suspense"
 
-      # Special element: <rsc-suspense> → SuspenseElement (Suspense boundary)
-      if tag == "rsc-suspense"
-        fallback_text = node["data-rsc-fallback"] || ""
-        fallback = if fallback_text.empty?
-                     nil
-                   else
-                     Flight::ReactElement.new(type: "p", key: nil, props: { "children" => fallback_text })
-                   end
+      props = build_props(node, tag)
+      children = convert_children(node)
+      props["children"] = children.length == 1 ? children.first : children unless children.empty?
 
-        child_nodes = node.children.reject { |n| ignorable?(n) }.filter_map { |n| convert_node(n) }
-        children = child_nodes.length == 1 ? child_nodes.first : child_nodes
+      Flight::ReactElement.new(type: tag, key: node["data-react-key"], props: props)
+    end
 
-        return Flight::SuspenseElement.new(fallback: fallback, children: children)
-      end
+    def convert_suspense_element(node)
+      fallback_text = node["data-ruact-fallback"] || ""
+      fallback = if fallback_text.empty?
+                   nil
+                 else
+                   Flight::ReactElement.new(type: "p", key: nil, props: { "children" => fallback_text })
+                 end
 
-      key = node["data-react-key"]
-      props = {}
+      child_nodes = convert_children(node)
+      children = child_nodes.length == 1 ? child_nodes.first : child_nodes
+
+      Flight::SuspenseElement.new(fallback: fallback, children: children)
+    end
 
+    def convert_children(node)
+      node.children.reject { |n| ignorable?(n) }.filter_map { |n| convert_node(n) }
+    end
+
+    def build_props(node, tag)
+      props = {}
       node.attributes.each do |attr_name, attr_node|
         next if attr_name == "data-react-key"
 
-        react_name = if attr_name == "value" && %w[textarea select].include?(tag)
-                       "defaultValue"
-                     elsif attr_name == "value" && tag == "input"
-                       input_type = node["type"]&.downcase
-                       %w[submit reset button image].include?(input_type) ? "value" : "defaultValue"
-                     elsif attr_name == "checked" && tag == "input"
-                       "defaultChecked"
-                     else
-                       HTML_TO_REACT[attr_name] || camel_case_data(attr_name)
-                     end
+        react_name = react_attr_name(attr_name, tag, node)
         props[react_name] = attr_name == "style" ? parse_style(attr_node.value) : attr_node.value
       end
+      props
+    end
 
-      children = node.children.reject { |n| ignorable?(n) }.filter_map { |n| convert_node(n) }
+    def react_attr_name(attr_name, tag, node)
+      return "defaultValue" if attr_name == "value" && DEFAULT_VALUE_TAGS.include?(tag)
+      return input_value_name(node) if attr_name == "value" && tag == "input"
+      return "defaultChecked" if attr_name == "checked" && tag == "input"
 
-      unless children.empty?
-        props["children"] = children.length == 1 ? children.first : children
-      end
+      HTML_TO_REACT[attr_name] || camel_case_data(attr_name)
+    end
 
-      Flight::ReactElement.new(type: tag, key: key, props: props)
+    def input_value_name(node)
+      input_type = node["type"]&.downcase
+      INPUT_BUTTON_TYPES.include?(input_type) ? "value" : "defaultValue"
     end
 
     # Converts a CSS inline style string into a React-compatible hash with camelCase keys.
@@ -156,4 +255,5 @@ module Ruact
       parts.first + parts[1..].map(&:capitalize).join
     end
   end
+  # rubocop:enable Metrics/ClassLength
 end

data/lib/ruact/query.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Story 9.4 (route-driven redesign, Phase B) — base class for v2 server
+  # QUERIES. Queries are plain classes under `app/queries/`; each public
+  # instance method defined directly on the subclass is one query:
+  #
+  #   # app/queries/application_query.rb
+  #   class ApplicationQuery < Ruact::Query; end
+  #
+  #   # app/queries/catalog_query.rb
+  #   class CatalogQuery < ApplicationQuery
+  #     def categories
+  #       Category.active.pluck(:id, :name).map { |id, name| { value: id, label: name } }
+  #     end
+  #
+  #     def my_categories
+  #       current_user.categories.pluck(:id, :name)
+  #     end
+  #   end
+  #
+  #   # config/routes.rb
+  #   Rails.application.routes.draw do
+  #     ruact_queries CatalogQuery   # GET /q/categories, GET /q/myCategories — visible in `rails routes`
+  #   end
+  #
+  # Per the 2026-06-02 ADR addendum (Decision 2), dispatch goes through an
+  # internal gem controller that inherits `Ruact.config.query_parent_controller`
+  # (default `ApplicationController`) — the host's REAL callback chain
+  # (`authenticate_user!`, tenant scoping, Pundit) runs BEFORE the query class
+  # is instantiated (FR89). The query instance is fresh per request (NFR8) and
+  # receives its execution context via the constructor, so
+  # `CatalogQuery.new(fake_context).categories` is unit-testable with no Rails
+  # boot.
+  #
+  # The context accessors below are defined on `Ruact::Query` itself, so they
+  # are INHERITED by subclasses — they never appear in a subclass's
+  # `public_instance_methods(false)`, which is exactly the set the
+  # `ruact_queries` routing macro mounts (one named GET route per method).
+  class Query
+    # @param context [#current_user, #params, #request, #session] the
+    #   per-request execution context. In production this is a
+    #   {Ruact::ServerFunctions::QueryContext} wrapping the dispatching
+    #   controller; in unit tests any object exposing the four readers works.
+    def initialize(context)
+      @__ruact_context = context
+    end
+
+    # @return [Object, nil] the host's authenticated user, via the dispatching
+    #   controller's own `current_user` (Devise / Pundit / hand-rolled).
+    def current_user
+      @__ruact_context.current_user
+    end
+
+    # @return [Object] the request params (query-string parameters on a GET).
+    def params
+      @__ruact_context.params
+    end
+
+    # @return [Object] the live request.
+    def request
+      @__ruact_context.request
+    end
+
+    # @return [Object] the host middleware's session.
+    def session
+      @__ruact_context.session
+    end
+
+    class << self
+      # Story 9.4 AC4 / D1 — per-query callback opt-out (resolves ADR open
+      # item 1). Mirrors Rails' `skip_before_action` ergonomics; the recorded
+      # skips are applied verbatim to THIS query class's generated dispatch
+      # controller when `ruact_queries` draws its routes, so the opt-out never
+      # leaks to other query classes:
+      #
+      #   class PublicCatalogQuery < ApplicationQuery
+      #     ruact_skip_before_action :authenticate_user!
+      #
+      #     def categories = Category.pluck(:id, :name)
+      #   end
+      #
+      # Options are forwarded to `skip_before_action` untouched — `only:` /
+      # `except:` scope the skip to specific query methods (each method is one
+      # controller action), `raise: false` tolerates a callback the parent
+      # does not define.
+      #
+      # @param callbacks [Array<Symbol>] callback name(s) to skip.
+      # @param options [Hash] forwarded to `skip_before_action` verbatim.
+      # @return [void]
+      def ruact_skip_before_action(*callbacks, **options)
+        __ruact_skipped_callbacks << [callbacks.map(&:to_sym), options]
+        nil
+      end
+
+      # The recorded `(callbacks, options)` pairs for this query class,
+      # consumed by {Ruact::ServerFunctions::QueryDispatch} when the dispatch
+      # controller is generated. Per-class (not inherited) — a skip describes
+      # the queries of the class that declares it.
+      #
+      # @return [Array<Array(Array<Symbol>, Hash)>]
+      def __ruact_skipped_callbacks
+        @__ruact_skipped_callbacks ||= []
+      end
+    end
+  end
+end