ruact 0.0.1

data/lib/ruact/flight/serializer.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "json"
+require "date"
+
+module Ruact
+  module Flight
+    # Converts a Ruby value/element tree into Flight wire format rows.
+    # All methods return the *inline* representation of the value
+    # (what goes inside a parent row). Side effects go into request queues.
+    class Serializer
+      # Strings larger than this are outlined into their own T row.
+      LARGE_TEXT_THRESHOLD = 1024
+
+      def initialize(request)
+        @request = request
+      end
+
+      # Entry point. Returns a value safe to pass to JSON.generate.
+      def serialize_model(value)
+        case value
+        when NilClass
+          nil
+        when TrueClass, FalseClass
+          value
+        when Integer
+          serialize_integer(value)
+        when Float
+          serialize_float(value)
+        when String
+          serialize_string(value)
+        when Symbol
+          serialize_symbol(value)
+        when Time, DateTime
+          serialize_date(value)
+        when ClientReference
+          serialize_client_reference(value)
+        when SuspenseElement
+          serialize_suspense(value)
+        when ReactElement
+          serialize_element(value)
+        when Array
+          serialize_array(value)
+        when Hash
+          serialize_hash(value)
+        else
+          serialize_unknown(value)
+        end
+      end
+
+      private
+
+      # --- Primitives ---
+
+      def serialize_string(value)
+        # Large strings get their own T row
+        if value.bytesize >= LARGE_TEXT_THRESHOLD
+          id = @request.allocate_id
+          @request.increment_pending
+          row = RowEmitter.text(id, value)
+          @request.completed_regular_chunks << row
+          return "$T#{id.to_s(16)}"
+        end
+
+        # Escape leading $ so the client doesn't misinterpret it.
+        # "$danger" → "$$danger" (prepend one extra $, not two)
+        value.start_with?("$") ? "$#{value}" : value
+      end
+
+      def serialize_integer(value)
+        # BigInt range check (JS safe integer: ±2^53 - 1)
+        if value.abs > 9_007_199_254_740_991
+          "$n#{value}"
+        else
+          value
+        end
+      end
+
+      def serialize_float(value)
+        return "$NaN"       if value.nan?
+        return "$Infinity"  if value.infinite? == 1
+        return "$-Infinity" if value.infinite? == -1
+        return "$-0"        if value.zero? && (1.0 / value).infinite? == -1
+
+        value
+      end
+
+      def serialize_symbol(value)
+        # Only :undefined is special for now
+        return "$undefined" if value == :undefined
+
+        # Unknown symbols: just use the name as a string
+        value.to_s
+      end
+
+      def serialize_date(value)
+        "$D#{value.iso8601(3)}"
+      end
+
+      # --- Collections ---
+
+      def serialize_array(value)
+        value.map { |v| serialize_model(v) }
+      end
+
+      def serialize_hash(value)
+        value.transform_keys(&:to_s).transform_values { |v| serialize_model(v) }
+      end
+
+      # --- React Element ---
+
+      def serialize_element(element)
+        type = element.type
+
+        resolved_type = case type
+                        when String
+                          # DOM element ("div", "span", etc.) — pass through as-is
+                          type
+                        when ClientReference
+                          serialize_client_reference(type)
+                        else
+                          raise TypeError, "Unsupported element type: #{type.inspect}"
+                        end
+
+        key   = element.key
+        props = serialize_hash(element.props)
+
+        ["$", resolved_type, key, props]
+      end
+
+      # --- Suspense Boundary ---
+
+      def serialize_suspense(element)
+        # Allocate ID for the deferred content row (emitted after root row + delay)
+        deferred_id = @request.allocate_id
+        @request.deferred_chunks << { id: deferred_id, element: element.children, delay: element.delay }
+
+        fallback_value = element.fallback ? serialize_model(element.fallback) : nil
+
+        # Children is an element tuple using the lazy ref as its type
+        lazy_ref = "$L#{deferred_id.to_s(16)}"
+        children_el = ["$", lazy_ref, nil, {}]
+
+        ["$", "$SS", nil, { "fallback" => fallback_value, "children" => children_el }]
+      end
+
+      # --- Unknown type fallback ---
+
+      def serialize_unknown(value)
+        return serialize_serializable(value) if value.is_a?(Ruact::Serializable)
+
+        if value.respond_to?(:as_json)
+          if @request.strict_serialization
+            raise Ruact::SerializationError,
+                  "Cannot serialize #{value.class.name} — " \
+                  "include Ruact::Serializable or set strict_serialization: false"
+          else
+            serialize_as_json(value)
+          end
+        else
+          raise Ruact::SerializationError,
+                "Cannot serialize #{value.class.name} — include Ruact::Serializable"
+        end
+      end
+
+      # --- Serializable (explicit opt-in, no warning) ---
+
+      def serialize_serializable(value)
+        serialize_model(value.rsc_serialize)
+      end
+
+      # --- as_json fallback (strict_serialization: false only) ---
+
+      def serialize_as_json(value)
+        data = begin
+          value.as_json
+        rescue StandardError => e
+          raise Ruact::SerializationError,
+                "#{value.class.name}#as_json raised #{e.class}: #{e.message}"
+        end
+
+        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"
+        end
+
+        attr_names = data.is_a?(Hash) ? data.keys.join(", ") : ""
+        @request.on_as_json_warning&.call(value.class.name, attr_names)
+        serialize_model(data)
+      end
+
+      # --- Client Reference ---
+
+      def serialize_client_reference(ref)
+        # Deduplication: same object → same $L reference
+        existing = @request.written_objects[ref]
+        return existing if existing
+
+        metadata = @request.bundler_config.resolve(ref.module_id, ref.export_name)
+
+        id = @request.allocate_id
+        @request.increment_pending
+
+        json = JSON.generate(metadata)
+        row  = RowEmitter.import(id, json)
+        @request.completed_import_chunks << row
+
+        lazy_ref = "$L#{id.to_s(16)}"
+        @request.written_objects[ref] = lazy_ref
+        lazy_ref
+      end
+    end
+  end
+end

data/lib/ruact/flight.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "flight/react_element"
+require_relative "flight/request"
+require_relative "flight/row_emitter"
+require_relative "flight/serializer"
+require_relative "flight/renderer"
+
+module Ruact
+  module Flight
+  end
+end

data/lib/ruact/html_converter.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Ruact
+  # Converts an HTML string (ERB output) into a ReactElement tree.
+  #
+  # 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
+  # - Text nodes → plain Ruby strings
+  # - Multiple root nodes → wrapped in a Fragment (array)
+  class HtmlConverter
+    # HTML attribute → React prop name mapping
+    HTML_TO_REACT = {
+      "class" => "className",
+      "for" => "htmlFor",
+      "tabindex" => "tabIndex",
+      "readonly" => "readOnly",
+      "maxlength" => "maxLength",
+      "cellpadding" => "cellPadding",
+      "cellspacing" => "cellSpacing",
+      "rowspan" => "rowSpan",
+      "colspan" => "colSpan",
+      "crossorigin" => "crossOrigin",
+      "autocomplete" => "autoComplete",
+      "autofocus" => "autoFocus",
+      "accesskey" => "accessKey",
+      "contenteditable" => "contentEditable",
+      "enctype" => "encType",
+      "formaction" => "formAction",
+      "novalidate" => "noValidate",
+      "spellcheck" => "spellCheck"
+    }.freeze
+
+    # Convert an HTML string into a ReactElement tree.
+    # component_registry is an array of { token:, name:, ref: ClientReference, props: Hash }
+    def self.convert(html, component_registry = [])
+      new(component_registry).convert(html)
+    end
+
+    def initialize(component_registry)
+      @registry = component_registry
+    end
+
+    def convert(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)
+      children = doc.children.reject { |n| ignorable?(n) }.filter_map { |n| convert_node(n) }
+
+      case children.length
+      when 0 then nil
+      when 1 then children.first
+      else        children # Fragment: array of elements
+      end
+    end
+
+    private
+
+    def ignorable?(node)
+      node.text? && node.text.strip.empty?
+    end
+
+    def convert_node(node)
+      case node.type
+      when Nokogiri::XML::Node::TEXT_NODE
+        text = node.text
+        text.strip.empty? ? nil : text
+
+      when Nokogiri::XML::Node::COMMENT_NODE
+        # Check if this is an RSC component placeholder
+        token = node.content.strip
+        entry = @registry.find { |c| c[:token] == token }
+        return nil unless entry
+
+        Flight::ReactElement.new(
+          type: entry[:ref],
+          key: nil,
+          props: entry[:props]
+        )
+
+      when Nokogiri::XML::Node::ELEMENT_NODE
+        convert_element(node)
+
+      end
+    end
+
+    def convert_element(node)
+      tag = node.name.downcase
+
+      # 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
+
+        child_nodes = node.children.reject { |n| ignorable?(n) }.filter_map { |n| convert_node(n) }
+        children = child_nodes.length == 1 ? child_nodes.first : child_nodes
+
+        return Flight::SuspenseElement.new(fallback: fallback, children: children)
+      end
+
+      key = node["data-react-key"]
+      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
+        props[react_name] = attr_name == "style" ? parse_style(attr_node.value) : attr_node.value
+      end
+
+      children = node.children.reject { |n| ignorable?(n) }.filter_map { |n| convert_node(n) }
+
+      unless children.empty?
+        props["children"] = children.length == 1 ? children.first : children
+      end
+
+      Flight::ReactElement.new(type: tag, key: key, props: props)
+    end
+
+    # Converts a CSS inline style string into a React-compatible hash with camelCase keys.
+    # e.g. "font-size:16px;color:red" → {"fontSize" => "16px", "color" => "red"}
+    def parse_style(css_string)
+      css_string.split(";").each_with_object({}) do |decl, hash|
+        prop, _, value = decl.partition(":")
+        prop  = prop.strip
+        value = value.strip
+        next if prop.empty? || value.empty?
+
+        camel = prop.split("-").each_with_index.map { |part, i| i.zero? ? part : part.capitalize }.join
+        hash[camel] = value
+      end
+    end
+
+    # data-foo-bar → "data-foo-bar" (kept as-is; React accepts kebab data attrs)
+    # other kebab attrs not in the map → camelCase
+    def camel_case_data(name)
+      return name if name.start_with?("data-", "aria-")
+
+      parts = name.split("-")
+      parts.first + parts[1..].map(&:capitalize).join
+    end
+  end
+end

data/lib/ruact/railtie.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "rails"
+
+module Ruact
+  class Railtie < Rails::Railtie
+    initializer "ruact.load_controller" do
+      require_relative "controller"
+    end
+
+    rake_tasks do
+      load File.expand_path("../tasks/rsc.rake", __dir__)
+    end
+
+    # Load the client manifest at boot (and on each code reload in development).
+    # config.to_prepare runs once in production and before every code reload in
+    # development, ensuring the manifest is always current without file I/O per
+    # request.
+    #
+    # Missing manifest behaviour (AC#5, #6):
+    # - development: logs a [ruact] warning; app starts normally
+    # - production:  raises ManifestError; app does not start
+    #
+    # Also registers ActionView integration:
+    # - ViewHelper provides __rsc_component__ in every view context
+    # - ErbPreprocessorHook applies the RSC preprocessor to all ERB templates
+    #   (layouts, views, partials) transparently via prepend.
+    config.to_prepare do
+      manifest_path = Ruact.config.manifest_path ||
+                      Rails.root.join("public", "react-client-manifest.json")
+      manifest_path = Pathname.new(manifest_path) unless manifest_path.respond_to?(:exist?)
+
+      if manifest_path.exist?
+        Ruact.manifest = Ruact::ClientManifest.load(manifest_path)
+      else
+        Ruact::Railtie.check_manifest!(manifest_path)
+      end
+
+      require_relative "view_helper"
+      require_relative "erb_preprocessor_hook"
+      ActionView::Base.include(Ruact::ViewHelper)
+      ActionView::Template::Handlers::ERB.prepend(Ruact::ErbPreprocessorHook)
+    end
+
+    # Detect streaming capability at boot and log the active mode (AC#1–3).
+    # Also warns in development if the Vite dev server is not running (AC#4, #7).
+    config.after_initialize do
+      Ruact::Railtie.detect_streaming_mode!
+      next unless Rails.env.development?
+
+      Ruact::Railtie.check_vite!
+    end
+
+    # Detects the web server at boot, stores the streaming mode, and logs the result (AC#1–3).
+    # Detection is constant-based (zero I/O): Puma → enabled, Unicorn/Passenger → buffered,
+    # unknown → buffered (safe mode).
+    def self.detect_streaming_mode!
+      mode, label = if defined?(::Puma::Server)
+                      [:enabled,  "Puma detected"]
+                    elsif defined?(::Falcon::Server)
+                      [:enabled,  "Falcon detected"]
+                    elsif defined?(::Unicorn)
+                      [:buffered, "Unicorn detected"]
+                    elsif defined?(::PhusionPassenger)
+                      [:buffered, "Passenger detected"]
+                    else
+                      [:buffered, "server unknown — defaulting to safe mode"]
+                    end
+
+      Ruact.streaming_mode = mode
+      verb = mode == :enabled ? "enabled" : "buffered"
+      Rails.logger.info "[ruact] streaming: #{verb} (#{label})"
+      mode
+    end
+
+    # Checks whether the Vite dev server is accessible and warns if not (AC#4).
+    # Extracted as a class method for direct testability without a full Rails app.
+    def self.check_vite!
+      require "socket"
+      TCPSocket.new("localhost", 5173).close
+    rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH
+      Rails.logger.warn "[ruact] Vite dev server not detected at localhost:5173 " \
+                        "— run npm run dev for HMR"
+    end
+
+    # Checks whether the manifest exists and either warns (dev) or raises (prod).
+    # Extracted as a class method for direct testability without a full Rails app.
+    def self.check_manifest!(manifest_path)
+      if Rails.env.production?
+        raise ManifestError,
+              "react-client-manifest.json not found — run vite build before deploying"
+      else
+        Rails.logger.warn "[ruact] react-client-manifest.json not found at " \
+                          "#{manifest_path} — RSC rendering will be unavailable. " \
+                          "Run 'npm run build' or start the Vite dev server."
+      end
+    end
+  end
+end

data/lib/ruact/render_pipeline.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Ruact
+  # Orchestrates the full server component render:
+  #   ERB source → (preprocessor) → evaluated HTML → (HtmlConverter) → ReactElement tree
+  #                                                                    → (Flight::Renderer) → wire bytes
+  #
+  # Two entry points:
+  #   call/stream — full pipeline from ERB source (used in unit tests and legacy path)
+  #   from_html   — takes pre-rendered HTML from ActionView (used by Controller#rsc_render)
+  class RenderPipeline
+    def initialize(manifest, controller_path: nil, logger: nil)
+      @manifest         = manifest
+      @controller_path  = controller_path
+      @logger           = logger
+    end
+
+    # Render ERB source within a given binding, return Flight wire format string.
+    # Deferred chunk delays are skipped — suitable for buffered responses (HTML shell).
+    def call(erb_source, binding_context)
+      _stream(erb_source, binding_context, streaming: false).to_a.join
+    end
+
+    # Render ERB source and return an Enumerator that yields Flight rows one at a time.
+    # Deferred chunk delays ARE applied — suitable for ActionController::Live streaming.
+    def stream(erb_source, binding_context)
+      _stream(erb_source, binding_context, streaming: true)
+    end
+
+    # Convert pre-rendered HTML (from ActionView) to Flight wire rows.
+    #
+    # IMPORTANT — Eager registry capture: ComponentRegistry.components is read
+    # immediately when this method is called, before the Enumerator is returned.
+    # This allows the caller to call ComponentRegistry.reset right after from_html
+    # returns (inside an ensure block) without affecting the captured registry.
+    #
+    # The returned Enumerator does NOT reference ComponentRegistry at all —
+    # only the eagerly-captured +registry+ local variable.
+    def from_html(html, streaming: false)
+      registry = ComponentRegistry.components.map do |entry|
+        ref = @manifest.reference_for(entry[:name], controller_path: @controller_path)
+        { token: entry[:token], name: entry[:name], ref: ref, props: entry[:props] }
+      end
+      strict = Ruact.config.strict_serialization
+      warning_cb = as_json_warning_callback
+
+      Enumerator.new do |y|
+        root_element = HtmlConverter.convert(html, registry)
+        Flight::Renderer.each(root_element, @manifest,
+                              strict_serialization: strict,
+                              on_as_json_warning: warning_cb,
+                              streaming: streaming) { |row| y << row }
+      end
+    end
+
+    private
+
+    def _stream(erb_source, binding_context, streaming: false)
+      Enumerator.new do |y|
+        ComponentRegistry.start
+        begin
+          transformed = ErbPreprocessor.transform(erb_source)
+          inject_helper!(binding_context)
+          html = ERB.new(transformed).result(binding_context)
+
+          registry = ComponentRegistry.components.map do |entry|
+            ref = @manifest.reference_for(entry[:name], controller_path: @controller_path)
+            { token: entry[:token], name: entry[:name], ref: ref, props: entry[:props] }
+          end
+
+          root_element = HtmlConverter.convert(html, registry)
+
+          Flight::Renderer.each(root_element, @manifest,
+                                strict_serialization: Ruact.config.strict_serialization,
+                                on_as_json_warning: as_json_warning_callback,
+                                streaming: streaming) { |row| y << row }
+        ensure
+          ComponentRegistry.reset
+        end
+      end
+    end
+
+    def as_json_warning_callback
+      return nil if @logger.nil?
+
+      lambda do |class_name, attrs|
+        @logger.warn(
+          "[ruact] WARNING: #{class_name} serialized via as_json — " \
+          "ALL attributes exposed to client: #{attrs}. " \
+          "Use `include Ruact::Serializable` with `rsc_props` for explicit control"
+        )
+      end
+    end
+
+    # Define __rsc_component__ in the ERB binding so it can be called.
+    def inject_helper!(binding_context)
+      binding_context.eval(<<~RUBY)
+        def __rsc_component__(name, props = {})
+          token = ::Ruact::ComponentRegistry.register(name, props)
+          "<!-- \#{token} -->"
+        end
+      RUBY
+    end
+  end
+end

data/lib/ruact/serializable.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Ruact
+  # Include this module in any Ruby object you want to pass as a prop to a
+  # client component. Declare which attributes are safe to serialize with
+  # +rsc_props+; only those attributes will be included in the wire payload.
+  #
+  # @example
+  #   class Post
+  #     include Ruact::Serializable
+  #     attr_reader :id, :title, :secret
+  #     rsc_props :id, :title   # :secret is never sent to the client
+  #   end
+  module Serializable
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.instance_variable_set(:@rsc_props, [])
+    end
+
+    module ClassMethods
+      # Declare which instance methods should be included in the serialized
+      # payload. Raises +ArgumentError+ at class-load time if any name has no
+      # corresponding method defined on the class.
+      #
+      # @param attrs [Array<Symbol>]
+      def rsc_props(*attrs)
+        attrs.each do |attr|
+          unless method_defined?(attr)
+            raise ArgumentError,
+                  "rsc_props: method `#{attr}` is not defined on #{self}"
+          end
+        end
+        @rsc_props = attrs
+      end
+
+      # Returns the list of declared prop names as symbols.
+      # Walks the ancestor chain so subclasses inherit parent declarations.
+      #
+      # @return [Array<Symbol>]
+      def rsc_props_list
+        klass = self
+        while klass
+          return klass.instance_variable_get(:@rsc_props) if klass.instance_variable_defined?(:@rsc_props)
+
+          klass = klass.superclass
+        end
+        []
+      end
+    end
+
+    # Serialize only the attributes declared with +rsc_props+.
+    #
+    # @return [Hash{String => Object}]
+    def rsc_serialize
+      self.class.rsc_props_list.to_h { |attr| [attr.to_s, public_send(attr)] }
+    end
+  end
+end

data/lib/ruact/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Ruact
+  VERSION = "0.0.1"
+end

data/lib/ruact/view_helper.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Ruact
+  # ActionView helper module included in ActionView::Base via Railtie.
+  # Provides the +__rsc_component__+ method that ERB templates call after the
+  # preprocessor transforms PascalCase tags into +<%= __rsc_component__(...) %>+.
+  #
+  # Thread-safe: ActionView creates a fresh view context per request, so there
+  # is no shared state between concurrent requests.
+  module ViewHelper
+    # Registers +name+ with +props+ in the per-request ComponentRegistry and
+    # returns an HTML comment placeholder that HtmlConverter later replaces with
+    # a ReactElement node.
+    #
+    # The returned string MUST be html_safe so ActionView does not escape the
+    # angle brackets — if it were escaped, HtmlConverter would not find the
+    # placeholder in the HTML output.
+    def __rsc_component__(name, props = {})
+      token = ComponentRegistry.register(name, props)
+      "<!-- #{token} -->".html_safe
+    end
+  end
+end