react_on_rails 17.0.1 → 17.1.0.rc.0

data/lib/react_on_rails/doctor_schema.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module ReactOnRails
+  # Public contract for the machine-readable doctor report.
+  #
+  # Check IDs are stable identifiers for automation. Never rename or reuse one;
+  # add a new ID for a new check. Additive fields may be introduced without a
+  # schema version bump, but removing or changing a documented field requires a
+  # new version.
+  module DoctorSchema
+    VERSION = 1
+    STATUS_SEVERITIES = { "pass" => "info", "warn" => "warning", "fail" => "error" }.freeze
+    STATUSES = STATUS_SEVERITIES.keys.freeze
+    SEVERITIES = STATUS_SEVERITIES.values.uniq.freeze
+    DETAIL_LEVELS = %w[success warning error info].freeze
+    EXIT_CODES = { pass: 0, warn: 0, fail: 1 }.freeze
+    DOCS_URL = "https://reactonrails.com/docs/api-reference/doctor"
+
+    CHECK_METADATA = {
+      "environment_prerequisites" => {
+        files: ["package.json", "package manager lockfile"],
+        expected_end_state: "Node.js and the app's JavaScript package manager are installed and detected."
+      },
+      "react_on_rails_versions" => {
+        files: ["Gemfile", "package.json", "package manager lockfile"],
+        expected_end_state: "The React on Rails gem and npm package versions are compatible and pinned safely."
+      },
+      "react_on_rails_packages" => {
+        files: ["Gemfile", "config/shakapacker.yml", "config/webpack", "config/rspack"],
+        expected_end_state: "Shakapacker is installed and its configured bundler files exist."
+      },
+      "javascript_package_dependencies" => {
+        files: ["package.json", "package manager lockfile"],
+        expected_end_state: "Required React and React on Rails JavaScript dependencies are installed and compatible."
+      },
+      "key_configuration_files" => {
+        files: ["config/initializers/react_on_rails.rb", "config/shakapacker.yml", "app/javascript"],
+        expected_end_state: "The generated React on Rails configuration files exist and match the app setup."
+      },
+      "configuration_analysis" => {
+        files: ["config/initializers/react_on_rails.rb", "config/shakapacker.yml", "app/views/layouts"],
+        expected_end_state: "React on Rails, Shakapacker, and server bundle settings agree."
+      },
+      "bin_dev_launcher_setup" => {
+        files: ["bin/dev", "Procfile.dev", "Procfile.dev-static-assets"],
+        expected_end_state: "The development launcher starts Rails and the configured asset bundler correctly."
+      },
+      "rails_integration" => {
+        files: ["config/initializers/react_on_rails.rb", "config/application.rb"],
+        expected_end_state: "Rails loads the React on Rails initializer successfully."
+      },
+      "bundler_configuration" => {
+        files: ["config/shakapacker.yml", "config/webpack", "config/rspack"],
+        expected_end_state: "The configured webpack or Rspack entry point is present and valid."
+      },
+      "testing_setup" => {
+        files: ["spec/rails_helper.rb", "spec/spec_helper.rb", "test/test_helper.rb"],
+        expected_end_state: "The test suite builds React assets before tests that need them."
+      },
+      "development_environment" => {
+        files: ["config/environments/development.rb", "config/shakapacker.yml", "package.json"],
+        expected_end_state: "The development server, HMR, and generated bundle settings are consistent."
+      },
+      "react_on_rails_pro_setup" => {
+        files: ["Gemfile", "package.json", "config/initializers/react_on_rails.rb"],
+        expected_end_state: "React on Rails Pro packages and configuration are mutually compatible."
+      },
+      "node_renderer_rollout_capacity" => {
+        files: ["renderer/node-renderer.js", "client/node-renderer.js", "deployment environment"],
+        expected_end_state:
+          "The NodeRenderer declares and prewarms its current server/RSC set, and its VM hard cap can hold " \
+          "rollout overlap."
+      },
+      "react_server_components" => {
+        files: ["config/initializers/react_on_rails.rb", "config/shakapacker.yml", "app/javascript"],
+        expected_end_state: "RSC packages, generated artifacts, and renderer configuration are consistent."
+      }
+    }.freeze
+
+    # A check section can contain several distinct diagnoses, so no section-wide
+    # repair command is currently safe. Keep fix_command nullable until a future
+    # diagnosis-specific contract can prove that one command repairs the exact finding.
+
+    module_function
+
+    def metadata(check_id)
+      CHECK_METADATA.fetch(check_id) do
+        raise ArgumentError, "Missing DoctorSchema::CHECK_METADATA entry for check id #{check_id.inspect}"
+      end
+    end
+
+    def docs_url(check_id)
+      "#{DOCS_URL}#check-id-#{check_id.tr('_', '-')}"
+    end
+
+    def summarize_statuses(statuses)
+      counts = statuses.tally
+      STATUSES.to_h { |status| [status.to_sym, counts.fetch(status, 0)] }
+    end
+
+    # Runtime validation keeps the emitted payload aligned with the documented
+    # contract without adding a runtime JSON-schema dependency to the gem.
+    def validate!(report)
+      required_keys!(report, %i[schema_version ror_version status checks summary], "report")
+      assert(report[:schema_version] == VERSION, "unsupported schema_version")
+      assert(report[:ror_version].is_a?(String), "ror_version must be a string")
+      assert(STATUSES.include?(report[:status]), "invalid report status")
+      assert(report[:checks].is_a?(Array), "checks must be an array")
+      report[:checks].each { |check| validate_check!(check) }
+      validate_unique_check_ids!(report[:checks])
+      validate_summary!(report)
+      report
+    end
+
+    def validate_check!(check)
+      required_keys!(check, %i[id title status severity message fix_command docs_url remediation details], "check")
+      assert(CHECK_METADATA.key?(check[:id]), "unknown check id #{check[:id].inspect}")
+      assert(STATUSES.include?(check[:status]), "invalid status for #{check[:id]}")
+      assert(SEVERITIES.include?(check[:severity]), "invalid severity for #{check[:id]}")
+      assert(check[:severity] == STATUS_SEVERITIES[check[:status]], "severity does not match status for #{check[:id]}")
+      validate_check_field_types!(check)
+      validate_details!(check)
+      validate_remediation!(check)
+    end
+
+    def validate_check_field_types!(check)
+      assert(check[:title].is_a?(String), "invalid title for #{check[:id]}")
+      assert(check[:message].nil? || check[:message].is_a?(String), "invalid message for #{check[:id]}")
+      assert(check[:fix_command].nil? || check[:fix_command].is_a?(String), "invalid fix_command for #{check[:id]}")
+      assert(check[:docs_url].is_a?(String), "invalid docs_url for #{check[:id]}")
+    end
+
+    def validate_details!(check)
+      assert(check[:details].is_a?(Array), "details must be an array for #{check[:id]}")
+      check[:details].each { |detail| validate_detail!(detail, check[:id]) }
+    end
+
+    def validate_detail!(detail, check_id)
+      required_keys!(detail, %i[level content], "detail for #{check_id}")
+      assert(DETAIL_LEVELS.include?(detail[:level]), "invalid detail level for #{check_id}")
+      assert(detail[:content].is_a?(String), "invalid detail content for #{check_id}")
+    end
+
+    def validate_remediation!(check)
+      remediation = check[:remediation]
+      if check[:status] == "pass"
+        assert(remediation.nil?, "passing check #{check[:id]} must not have remediation")
+        return
+      end
+
+      assert(remediation.is_a?(Hash), "non-passing check #{check[:id]} must have remediation")
+      required_keys!(remediation, %i[prompt files expected_end_state], "remediation")
+      assert(remediation[:prompt].is_a?(String) && !remediation[:prompt].empty?, "invalid remediation prompt")
+      assert(remediation[:files].is_a?(Array) && remediation[:files].all?(String), "invalid remediation files")
+      assert(remediation[:expected_end_state].is_a?(String), "invalid remediation expected_end_state")
+    end
+
+    def validate_unique_check_ids!(checks)
+      ids = checks.map { |check| check[:id] }
+      assert(ids.uniq.length == ids.length, "check ids must be unique")
+    end
+
+    def validate_summary!(report)
+      summary = report[:summary]
+      required_keys!(summary, %i[pass warn fail], "summary")
+      assert(summary.values.all? { |count| count.is_a?(Integer) && count >= 0 },
+             "summary values must be non-negative integers")
+
+      statuses = report[:checks].map { |check| check[:status] }
+      expected_summary = summarize_statuses(statuses)
+      assert(summary == expected_summary, "summary does not match checks")
+      assert(report[:status] == overall_status(statuses), "report status does not match checks")
+    end
+
+    def overall_status(statuses)
+      return "fail" if statuses.include?("fail")
+      return "warn" if statuses.include?("warn")
+
+      "pass"
+    end
+
+    def required_keys!(value, keys, label)
+      assert(value.is_a?(Hash), "#{label} must be an object")
+      missing = keys - value.keys
+      assert(missing.empty?, "#{label} missing keys: #{missing.join(', ')}")
+    end
+
+    def assert(condition, message)
+      raise ArgumentError, "Invalid doctor JSON report: #{message}" unless condition
+    end
+  end
+end

data/lib/react_on_rails/engine.rb

@@ -30,9 +30,9 @@ module ReactOnRails
       config.after_initialize do
         next if Engine.skip_version_validation?
 
-        Rails.logger.info "[React on Rails] Validating package version and compatibility..."
+        Rails.logger.debug "[React on Rails] Validating package version and compatibility..."
         VersionChecker.build.validate_version_and_package_compatibility!
-        Rails.logger.info "[React on Rails] Package validation successful"
+        Rails.logger.debug "[React on Rails] Package validation successful"
       end
     end
 

data/lib/react_on_rails/helper.rb

@@ -7,6 +7,7 @@
 # 1. The white spacing in this file matters!
 # 2. Keep all #{some_var} fully to the left so that all indentation is done evenly in that var
 require "react_on_rails/prerender_error"
+require "react_on_rails/json_parse_error"
 require "react_on_rails/smart_error"
 require "addressable/uri"
 require "react_on_rails/utils"
@@ -904,6 +905,20 @@ module ReactOnRails
       )
     end
 
+    def raise_renderer_prerender_error(err, react_component_name, props, js_code)
+      prerender_error = ReactOnRails::PrerenderError.new(component_name: react_component_name,
+                                                         # Sanitize as this might be browser logged
+                                                         props: sanitized_props_string(props),
+                                                         err:,
+                                                         js_code:)
+      renderer_parse_error = err.is_a?(ReactOnRails::JsonParseError) ||
+                             (defined?(ReactOnRails::LengthPrefixedParser::ParseError) &&
+                               err.is_a?(ReactOnRails::LengthPrefixedParser::ParseError))
+      raise prerender_error, cause: nil if renderer_parse_error
+
+      raise prerender_error
+    end
+
     def rendering_error_from_result(json_result)
       rendering_error = json_result["renderingError"]
       return unless rendering_error.is_a?(Hash)
@@ -987,11 +1002,7 @@ module ReactOnRails
         result = ReactOnRails::ServerRenderingPool.server_render_js_with_console_logging(js_code, render_options)
       rescue StandardError => err
         # This error came from the renderer
-        raise ReactOnRails::PrerenderError.new(component_name: react_component_name,
-                                               # Sanitize as this might be browser logged
-                                               props: sanitized_props_string(props),
-                                               err:,
-                                               js_code:)
+        raise_renderer_prerender_error(err, react_component_name, props, js_code)
       end
 
       if render_options.streaming?
@@ -1005,11 +1016,7 @@ module ReactOnRails
 
         result.rescue do |err|
           # This error came from the renderer
-          raise ReactOnRails::PrerenderError.new(component_name: react_component_name,
-                                                 # Sanitize as this might be browser logged
-                                                 props: sanitized_props_string(props),
-                                                 err:,
-                                                 js_code:)
+          raise_renderer_prerender_error(err, react_component_name, props, js_code)
         end
       elsif result["hasErrors"] && render_options.raise_on_prerender_error
         raise_prerender_error(result, react_component_name, props, js_code)

data/lib/react_on_rails/length_prefixed_parser.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require "react_on_rails/lenient_json"
 
 module ReactOnRails
   # Parses the length-prefixed wire format used between Node renderer and Ruby.
@@ -11,6 +12,8 @@ module ReactOnRails
   # Used by both streaming (Pro) and non-streaming (OSS) paths.
   # Strict protocol parser — any format violation raises an error.
   class LengthPrefixedParser
+    class ParseError < ReactOnRails::Error; end
+
     # Keep aligned with ReactOnRailsPro::StreamRequest::CONTROL_MESSAGE_TYPES,
     # which routes these same control frames during bidirectional streaming.
     # MIRROR VALUES OF: react_on_rails_pro/lib/react_on_rails_pro/stream_request.rb
@@ -28,11 +31,11 @@ module ReactOnRails
       results = []
       parser.feed(str.to_s.b) { |chunk| results << chunk }
       if results.empty?
-        raise ReactOnRails::Error,
+        raise ParseError,
               "Malformed render result: expected exactly one length-prefixed chunk but found none"
       end
       if results.size > 1
-        raise ReactOnRails::Error,
+        raise ParseError,
               "Malformed render result: expected exactly one length-prefixed chunk but found #{results.size}"
       end
       results.first
@@ -98,11 +101,7 @@ module ReactOnRails
       @buf = @buf.byteslice(idx + 1, @buf.bytesize - idx - 1)
 
       tab_idx = header.byteindex("\t".b)
-      unless tab_idx
-        header_str = header.force_encoding(Encoding::UTF_8).inspect
-        raise ReactOnRails::Error,
-              "Malformed length-prefixed header: missing tab separator in: #{header_str}"
-      end
+      raise ParseError, "Malformed length-prefixed header: missing tab separator" unless tab_idx
 
       parse_length_prefixed_header(header, tab_idx)
       true
@@ -115,16 +114,18 @@ module ReactOnRails
       begin
         @content_len = Integer(len_hex, 16)
       rescue ArgumentError
-        raise ReactOnRails::Error, "Invalid content length hex: #{len_hex.force_encoding(Encoding::UTF_8).inspect}"
+        raise ParseError, "Malformed length-prefixed header: invalid content length hex", cause: nil
       end
+      raise ParseError, "Malformed length-prefixed header: negative content length" if @content_len.negative?
 
       begin
-        @metadata = JSON.parse(meta_json.force_encoding(Encoding::UTF_8))
-      rescue JSON::ParserError => e
-        meta_str = meta_json.force_encoding(Encoding::UTF_8).inspect
-        raise ReactOnRails::Error,
-              "Malformed length-prefixed header: invalid metadata JSON: #{meta_str} (#{e.message})"
+        # LenientJson tolerates lone UTF-16 surrogates that the JS renderer can emit
+        # (e.g. from truncating a string mid-emoji) which stock JSON.parse rejects. See #4710.
+        @metadata = LenientJson.parse(meta_json.force_encoding(Encoding::UTF_8))
+      rescue JSON::ParserError
+        raise ParseError, "Malformed length-prefixed header: invalid metadata JSON", cause: nil
       end
+      raise ParseError, "Malformed length-prefixed header: metadata JSON must be an object" unless @metadata.is_a?(Hash)
 
       @state = :content
     end
@@ -153,7 +154,7 @@ module ReactOnRails
       #   "object" → JSON-serialized value (ServerRenderHash or null), needs JSON.parse
       #   "string" → raw HTML string, used as-is
       payload_type = @metadata.delete("payloadType")
-      @metadata["html"] = payload_type == "object" ? JSON.parse(raw_content) : raw_content
+      @metadata["html"] = payload_type == "object" ? parse_object_payload(raw_content) : raw_content
 
       result = @metadata
       @metadata = nil
@@ -161,5 +162,12 @@ module ReactOnRails
       yield result
       true
     end
+
+    def parse_object_payload(raw_content)
+      # See the metadata parse above: LenientJson repairs lone-surrogate escapes (#4710).
+      LenientJson.parse(raw_content)
+    rescue JSON::ParserError
+      raise ParseError, "Malformed length-prefixed object payload JSON", cause: nil
+    end
   end
 end

data/lib/react_on_rails/prerender_error.rb

@@ -5,7 +5,8 @@ require "rainbow"
 # rubocop:disable: Layout/IndentHeredoc
 module ReactOnRails
   class PrerenderError < ::ReactOnRails::Error
-    MAX_ERROR_SNIPPET_TO_LOG = 1000
+    REDACTED_VALUE = "[REDACTED]"
+    SENSITIVE_CONTEXT_KEYS = %w[props js_code json].freeze
     # TODO: Consider remove providing original `err` as already have access to `self.cause`
     # http://blog.honeybadger.io/nested-errors-in-ruby-with-exception-cause/
     attr_reader :component_name, :err, :props, :js_code, :console_messages
@@ -15,8 +16,8 @@ module ReactOnRails
                    js_code: nil, console_messages: nil)
       @component_name = component_name
       @err = err
-      @props = props
-      @js_code = js_code
+      @props = redacted_value(props)
+      @js_code = redacted_value(js_code)
       @console_messages = console_messages
 
       backtrace, message = calc_message(component_name, console_messages, err, js_code, props)
@@ -35,18 +36,43 @@ module ReactOnRails
     def to_error_context
       result = {
         component_name:,
-        err:,
+        err: error_context_value(err),
         props:,
         js_code:,
         console_messages:
       }
 
-      result.merge!(err.to_error_context) if err.respond_to?(:to_error_context)
+      if err.respond_to?(:to_error_context)
+        nested_context = err.to_error_context.reject { |key, _value| sensitive_nested_context_key?(key) }
+        result.merge!(nested_context)
+      end
       result
     end
 
     private
 
+    def renderer_parse_error?(error)
+      json_parse_error = defined?(JsonParseError) && error.is_a?(JsonParseError)
+      length_prefixed_parse_error = defined?(LengthPrefixedParser::ParseError) &&
+                                    error.is_a?(LengthPrefixedParser::ParseError)
+      json_parse_error || length_prefixed_parse_error
+    end
+
+    def safe_error_details(error)
+      return error.inspect unless renderer_parse_error?(error)
+
+      "#{error.class}: Renderer response could not be parsed"
+    end
+
+    def error_context_value(error)
+      renderer_parse_error?(error) ? safe_error_details(error) : error
+    end
+
+    def sensitive_nested_context_key?(key)
+      SENSITIVE_CONTEXT_KEYS.include?(key.to_s) ||
+        (renderer_parse_error?(err) && key.to_s == "original_error")
+    end
+
     # rubocop:disable Metrics/AbcSize
     def calc_message(component_name, console_messages, err, js_code, props)
       header = Rainbow("❌ React on Rails Server Rendering Error").red.bright
@@ -57,7 +83,7 @@ module ReactOnRails
       if err
         message << Rainbow("Error Details:").red.bright << "\n"
         message << <<~MSG
-          #{err.inspect}
+          #{safe_error_details(err)}
 
         MSG
 
@@ -68,11 +94,11 @@ module ReactOnRails
 
       # Add props information
       message << Rainbow("Props:").blue.bright << "\n"
-      message << "#{Utils.smart_trim(props, MAX_ERROR_SNIPPET_TO_LOG)}\n\n"
+      message << "#{redacted_value(props)}\n\n"
 
       # Add code snippet
       message << Rainbow("JavaScript Code:").blue.bright << "\n"
-      message << "#{Utils.smart_trim(js_code, MAX_ERROR_SNIPPET_TO_LOG)}\n\n"
+      message << "#{redacted_value(js_code)}\n\n"
 
       if console_messages && console_messages.strip.present?
         message << Rainbow("Console Output:").magenta.bright << "\n"
@@ -90,6 +116,10 @@ module ReactOnRails
       # rubocop:enable Metrics/AbcSize
     end
 
+    def redacted_value(value)
+      value.nil? ? nil : REDACTED_VALUE
+    end
+
     # Formats `err.backtrace` for display, or returns nil when there are no frames.
     def formatted_backtrace(err)
       error_backtrace = err.backtrace

data/lib/react_on_rails/react_component/render_options.rb

@@ -123,7 +123,7 @@ module ReactOnRails
       end
 
       def html_options
-        options[:html_options].to_h
+        options[:html_options].to_h.dup
       end
 
       def prerender