react_on_rails_pro 17.0.0.rc.4 → 17.0.0.rc.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45123dd7dda25991484169e21920b5c3d5cda2e2d517c38c0a0e3a5c8220f802
-  data.tar.gz: 6c3bb209b7fcbbd85a6cb2a5e9b035207ee50fb5466e087373536dde0dc638cc
+  metadata.gz: aa0bf219fe1d63080c7f653bd3496ea95f15a8e3a1a79a91dd6140de2f8415d9
+  data.tar.gz: 8d8ea4b6fd46b87c5411abbd9c01bd6e49ab9fa0bf026dfcf59cfa270a2e00c1
 SHA512:
-  metadata.gz: 7ba6fa338ab17e3793d0cedf6eb230384435e8b993b66b2dc2bc584a40d847e7ad23d25d05eff69e05369fcda4db381a750d3d8530819549076c5987558fbf66
-  data.tar.gz: d1abe0dd5e92fb32848bcef2bdad82c4083822157d77745f683a83764acd9670f205e9106f1c51c802a5f6caa1243628a8206ab28ee7f7362a3fe8ef72e9e60d
+  metadata.gz: 9e22fcd250f90618ccac39fabb7cbfecb60d502302c3cd1abd0d6bc3f9249c6552b0a25a9dcc235ef4d8c95c11223edc84eb9246bf67058f4ca70074756e9a8b
+  data.tar.gz: a6891194c45e31b9ce9a39a9dc31b5cb6807fa5a76bf64844aceaff5bbaacad0eefc9668ceeccdd5d7215c30739a37792918f8355a1094b0cd3339bda8921acd

data/.controlplane/postgres.yml

@@ -21,13 +21,18 @@ spec:
         - path: /var/lib/postgresql/data
           recoveryPolicy: retain
           uri: 'scratch://postgres-vol'
-  # Important that postgres does not scaling because disk storage is local to one server!
+  # Keep Postgres on one manual replica because disk storage is local to one server.
+  # Capacity AI may restart the workload when adjusting resources; for Postgres
+  # that can disrupt the database despite the retained local volume.
+  # Keep the single-replica manual posture explicit instead of relying on platform defaults.
   defaultOptions:
     autoscaling:
+      metric: disabled
+      minScale: 1
       maxScale: 1
     capacityAI: false
   # This firewall configuration corresponds to using a simple, hard-coded password for postgres
   # in the gvc.yml template.
   firewallConfig:
     internal:
-      inboundAllowType: same-gvc
+      inboundAllowType: same-gvc

data/.controlplane/rails.yml

@@ -47,11 +47,15 @@ spec:
         - number: 3800
           protocol: http
   defaultOptions:
-    # Start out like this for "test apps"
+    # Public/staging test apps keep one warm replica while Capacity AI right-sizes both workload
+    # containers (rails and node-renderer).
+    # Capacity AI may restart that replica when applying resource changes.
+    # For production or high-availability staging, increase maxScale and review Capacity AI suitability.
     autoscaling:
-      # Max of 1 effectively disables autoscaling, so a like a Heroku dyno count of 1
+      metric: disabled
+      minScale: 1
       maxScale: 1
-    capacityAI: false
+    capacityAI: true
   firewallConfig:
     external:
       # Default to allow public access to Rails server

data/.controlplane/redis.yml

@@ -22,7 +22,13 @@ spec:
         - number: 6379
           protocol: tcp
   defaultOptions:
+    # Capacity AI may restart the workload when adjusting resources; for Redis
+    # that can disrupt cache state and connections.
+    # Review cache restart tolerance before copying the Rails Capacity AI posture here.
+    # Keep the single-replica manual posture explicit instead of relying on platform defaults.
     autoscaling:
+      metric: disabled
+      minScale: 1
       maxScale: 1
     capacityAI: false
   # This firewall configuration corresponds to using no password for Redis in the gvc.yml template.

data/Gemfile.lock

@@ -9,7 +9,7 @@ GIT
 PATH
   remote: ..
   specs:
-    react_on_rails (17.0.0.rc.4)
+    react_on_rails (17.0.0.rc.6)
       addressable
       connection_pool
       execjs (~> 2.5)
@@ -20,7 +20,7 @@ PATH
 PATH
   remote: .
   specs:
-    react_on_rails_pro (17.0.0.rc.4)
+    react_on_rails_pro (17.0.0.rc.6)
       addressable
       async (>= 2.29)
       async-http (~> 0.95)
@@ -28,7 +28,7 @@ PATH
       io-endpoint (~> 0.17.0)
       jwt (>= 2.5, < 4)
       rainbow
-      react_on_rails (= 17.0.0.rc.4)
+      react_on_rails (= 17.0.0.rc.6)
 
 GEM
   remote: https://rubygems.org/

data/lib/react_on_rails_pro/async_props_emitter.rb

@@ -28,15 +28,40 @@ module ReactOnRailsPro
   # Global variables in Node.js VM persist across requests, causing data leakage.
   # sharedExecutionContext is scoped to a single HTTP request (ExecutionContext).
   #
-  # @example Usage in view
+  # PULL MODE:
+  # When pull_enabled is true, React components can request props lazily via
+  # getProp(). Those requests arrive as propRequest chunks on the response stream.
+  # `pull_requests` exposes an Async::Queue that yields prop names as they arrive.
+  # The user's block can dequeue and resolve them dynamically.
+  #
+  # @example Push-only usage (existing)
   #   stream_react_component_with_async_props("Dashboard") do |emit|
-  #     emit.call("users", User.all.to_a)      # Sends immediately
-  #     emit.call("posts", Post.recent.to_a)   # Sends when ready
+  #     emit.call("users", User.all.to_a)
+  #     emit.call("posts", Post.recent.to_a)
+  #   end
+  #
+  # @example Pull mode usage
+  #   stream_react_component_with_async_props("Dashboard", push_props: %w[stats]) do |emit|
+  #     emit.call("stats", compute_stats)
+  #     while (prop_name = emit.pull_requests.dequeue)
+  #       emit.call(prop_name, fetch_prop(prop_name))
+  #     end
   #   end
   class AsyncPropsEmitter
-    def initialize(bundle_timestamp, request_stream)
+    SANITIZED_REJECTION_REASON = "Async prop rejected by server"
+
+    attr_reader :pull_requests
+
+    def initialize(bundle_timestamp, request_stream, pull_enabled: false)
       @bundle_timestamp = bundle_timestamp
       @request_stream = request_stream
+      @pushed_props = Set.new
+      @pull_enabled = pull_enabled
+      @pull_requests = PullRequestQueue.new(@pushed_props) if pull_enabled
+    end
+
+    def pull_enabled?
+      @pull_enabled
     end
 
     # Sends an async prop to the Node renderer.
@@ -45,17 +70,35 @@ module ReactOnRailsPro
     def call(prop_name, prop_value)
       update_chunk = generate_update_chunk(prop_name, prop_value)
       @request_stream << "#{update_chunk.to_json}\n"
+      @pushed_props.add(prop_name)
     rescue StandardError => e
+      # Continue streaming: one failed async prop write should not abort the
+      # entire render. The prop is not marked as pushed unless the write
+      # succeeds, so pull mode can request it again instead of silently hanging.
       Rails.logger.error do
         backtrace = e.backtrace&.first(5)&.join("\n")
         "[ReactOnRailsPro::AsyncProps] Failed to send async prop '#{prop_name}': " \
           "#{e.class} - #{e.message}\n#{backtrace}"
       end
-      # Continue - don't abort entire render because one prop failed
     end
 
-    # Generates the chunk that should be executed when the request stream closes
-    # This tells the asyncPropsManager to end the stream
+    # Rejects an async prop on the Node side so React can show an error boundary.
+    def reject(prop_name, reason)
+      update_chunk = generate_reject_chunk(prop_name, reason)
+      @request_stream << "#{update_chunk.to_json}\n"
+      # Once the reject chunk is written, Ruby treats the prop as settled too.
+      # That keeps duplicate pull requests filtered even if the JS manager is recreated.
+      @pushed_props.add(prop_name)
+    rescue StandardError => e
+      Rails.logger.error do
+        backtrace = e.backtrace&.first(5)&.join("\n")
+        "[ReactOnRailsPro::AsyncProps] Failed to reject async prop '#{prop_name}': " \
+          "#{e.class} - #{e.message}\n#{backtrace}"
+      end
+    end
+
+    # Generates the chunk that should be executed when the request stream closes.
+    # This tells the asyncPropsManager to end the stream.
     def end_stream_chunk
       {
         bundleTimestamp: @bundle_timestamp,
@@ -63,6 +106,12 @@ module ReactOnRailsPro
       }
     end
 
+    # Called by stream_request when the response stream signals render complete.
+    # Closes the pull_requests queue so dequeue returns nil.
+    def render_complete!
+      @pull_requests&.close
+    end
+
     private
 
     def generate_update_chunk(prop_name, value)
@@ -72,6 +121,13 @@ module ReactOnRailsPro
       }
     end
 
+    def generate_reject_chunk(prop_name, reason)
+      {
+        bundleTimestamp: @bundle_timestamp,
+        updateChunk: generate_reject_prop_js(prop_name, reason)
+      }
+    end
+
     def generate_set_prop_js(prop_name, value)
       <<~JS.strip
         (function(){
@@ -81,6 +137,25 @@ module ReactOnRailsPro
       JS
     end
 
+    def generate_reject_prop_js(prop_name, reason)
+      <<~JS.strip
+        (function(){
+          var asyncPropsManager = ReactOnRails.getOrCreateAsyncPropsManager(sharedExecutionContext);
+          asyncPropsManager.rejectProp(#{prop_name.to_json}, #{sanitized_rejection_reason(reason).to_json});
+        })()
+      JS
+    end
+
+    # Always return the generic message regardless of the internal reason. Raw
+    # Rails-side details such as SQL errors, file paths, or credentials must not
+    # reach the browser. The raw reason is still emitted to debug logs for
+    # operators; keep it below info level because staging log aggregators may
+    # persist those details.
+    def sanitized_rejection_reason(reason)
+      Rails.logger.debug { "[ReactOnRailsPro::AsyncProps] Prop rejected (internal reason): #{reason}" }
+      SANITIZED_REJECTION_REASON
+    end
+
     def generate_end_stream_js
       <<~JS.strip
         (function(){
@@ -90,4 +165,46 @@ module ReactOnRailsPro
       JS
     end
   end
+
+  # Queue of prop names requested by React (pull mode).
+  # Wraps Async::Queue with automatic filtering of already-pushed props.
+  # dequeue returns nil after the queue is closed (render complete).
+  class PullRequestQueue
+    def initialize(pushed_props)
+      @queue = Async::Queue.new
+      @pushed_props = pushed_props
+      @closed = false
+    end
+
+    # Enqueue a propRequest from the Node renderer.
+    # Silently drops requests for props that have already been pushed.
+    def enqueue(prop_name)
+      # @pushed_props is mutated by AsyncPropsEmitter#call. In fiber-concurrent
+      # code this has a narrow TOCTOU window; duplicate requests are filtered on
+      # the TypeScript side via AsyncPropsManager's pullRequested flag.
+      return if @closed || @pushed_props.include?(prop_name)
+
+      @queue.enqueue(prop_name)
+    rescue Async::Queue::ClosedError
+      # Queue closed between the @closed guard and enqueue; safe to ignore.
+    end
+
+    # Blocks until a prop name is available, or returns nil if closed.
+    def dequeue
+      @queue.dequeue
+    rescue Async::Queue::ClosedError
+      nil
+    end
+
+    def close
+      return if @closed
+
+      @queue.close
+      @closed = true
+    end
+
+    def closed?
+      @closed
+    end
+  end
 end

data/lib/react_on_rails_pro/request.rb

@@ -87,13 +87,19 @@ module ReactOnRailsPro
       # - When the block finishes, we close the output (END_STREAM flag)
       # - Node's handleRequestClosed then calls asyncPropsManager.endStream()
       #
-      def render_code_with_incremental_updates(path, js_code, async_props_block:)
+      def render_code_with_incremental_updates(path, js_code, async_props_block:, pull_enabled: false, push_props: nil)
         Rails.logger.info { "[ReactOnRailsPro] Perform incremental rendering request #{path}" }
 
         pool = ReactOnRailsPro::ServerRenderingPool::NodeRenderingPool
+        if !push_props.nil? && !pull_enabled
+          raise ArgumentError, "push_props can only be provided when pull_enabled is true"
+        end
 
         warn_cb = ->(request_time) { warn_if_slow_streaming_first_chunk(path, request_time) }
-        ReactOnRailsPro::StreamRequest.create(first_chunk_warn_callback: warn_cb) do |send_bundle, tasks|
+        ReactOnRailsPro::StreamRequest.create(
+          first_chunk_warn_callback: warn_cb,
+          pull_enabled:
+        ) do |send_bundle, tasks|
           if send_bundle
             Rails.logger.info { "[ReactOnRailsPro] Sending bundle to the node renderer" }
             upload_assets
@@ -106,10 +112,14 @@ module ReactOnRailsPro
             headers: [["content-type", "application/x-ndjson"]]
           )
 
-          # Create emitter — output has the same interface as the old HTTPX request
-          # object (<< for writing, close for END_STREAM), so AsyncPropsEmitter works unchanged.
-          emitter = ReactOnRailsPro::AsyncPropsEmitter.new(pool.rsc_bundle_hash, output)
-          initial_data = build_initial_incremental_request(js_code, emitter)
+          emitter = ReactOnRailsPro::AsyncPropsEmitter.new(
+            pool.rsc_bundle_hash,
+            output,
+            pull_enabled:
+          )
+          initial_data = build_initial_incremental_request(
+            js_code, emitter, pull_enabled:, push_props:
+          )
 
           # Send the initial render request as first NDJSON line
           output << "#{initial_data.to_json}\n"
@@ -124,7 +134,7 @@ module ReactOnRailsPro
             output.close
           end)
 
-          response
+          { pull_result: true, response:, emitter: pull_enabled ? emitter : nil }
         end
       end
 
@@ -342,11 +352,16 @@ module ReactOnRailsPro
         ReactOnRailsPro::Utils.common_form_data
       end
 
-      def build_initial_incremental_request(js_code, emitter)
-        common_form_data.merge(
+      def build_initial_incremental_request(js_code, emitter, pull_enabled: false, push_props: nil)
+        data = common_form_data.merge(
           renderingRequest: js_code,
           onRequestClosedUpdateChunk: emitter.end_stream_chunk
         )
+        if pull_enabled
+          data[:pullEnabled] = true
+          data[:pushProps] = Array(push_props)
+        end
+        data
       end
 
       def create_connection

data/lib/react_on_rails_pro/server_rendering_pool/node_rendering_pool.rb

@@ -72,10 +72,16 @@ module ReactOnRailsPro
           if async_props_block
             # Use incremental rendering when async props block is provided
             path = prepare_incremental_render_path(js_code, render_options)
+            push_props = render_options.internal_option(:push_props)
+            # Pull mode is enabled whenever push_props is set, including [] for pure pull.
+            # nil means push-only mode with no bidirectional prop-request channel.
+            pull_enabled = !push_props.nil?
             ReactOnRailsPro::Request.render_code_with_incremental_updates(
               path,
               js_code,
-              async_props_block:
+              async_props_block:,
+              pull_enabled:,
+              push_props:
             )
           else
             # Use standard streaming when no async props block

data/lib/react_on_rails_pro/stream_request.rb

@@ -110,17 +110,21 @@ module ReactOnRailsPro
   end
 
   class StreamRequest
-    def http_status
-      @status
-    end
+    MAX_PULL_PROP_NAME_LENGTH = 256
+    # Keep aligned with ReactOnRails::LengthPrefixedParser::CONTROL_MESSAGE_TYPES,
+    # which parses these same control frames from the shared wire format.
+    CONTROL_MESSAGE_TYPES = %w[propRequest renderComplete].freeze
+    private_constant :CONTROL_MESSAGE_TYPES
 
-    def http_status_recorded?
-      @status_recorded
-    end
+    def http_status = @status
+
+    def http_status_recorded? = @status_recorded
 
-    def initialize(first_chunk_warn_callback: nil, &request_block)
+    def initialize(first_chunk_warn_callback: nil, pull_enabled: false, &request_block)
       @request_executor = request_block
       @first_chunk_warn_callback = first_chunk_warn_callback
+      @pull_enabled = pull_enabled
+      @emitter = nil
       @status = nil
       @status_recorded = false
     end
@@ -133,8 +137,8 @@ module ReactOnRailsPro
       Sync { consume_with_bundle_reupload(&block) }
     end
 
-    def self.create(first_chunk_warn_callback: nil, &request_block)
-      StreamDecorator.new(new(first_chunk_warn_callback:, &request_block))
+    def self.create(first_chunk_warn_callback: nil, pull_enabled: false, &request_block)
+      StreamDecorator.new(new(first_chunk_warn_callback:, pull_enabled:, &request_block))
     end
 
     private
@@ -151,9 +155,19 @@ module ReactOnRailsPro
           # response attempt.
           reset_response_status
           @received_first_chunk = false
-          stream_response = @request_executor.call(send_bundle, tasks)
-
-          process_response_chunks(stream_response, &block)
+          stream_response, @emitter = normalize_executor_result(@request_executor.call(send_bundle, tasks))
+
+          begin
+            process_response_chunks(stream_response, &block)
+          ensure
+            # renderComplete control messages normally close this queue earlier.
+            # This safety net covers parser errors, stream aborts, and timeouts
+            # before renderComplete arrives. The user's pull_requests.dequeue loop
+            # then exits with nil; any in-flight emit.call is protected by
+            # AsyncPropsEmitter#call's rescue.
+            @emitter&.render_complete!
+            @emitter = nil
+          end
           break
         rescue ReactOnRailsPro::RendererHttpClient::HTTPError => e
           stop_tasks(tasks) if retrying_with_bundle_upload?(e, send_bundle)
@@ -182,12 +196,9 @@ module ReactOnRailsPro
         record_status(stream_response) unless @status_recorded
         next if stream_response.error?
 
-        unless @received_first_chunk
-          @received_first_chunk = true
-          @first_chunk_warn_callback&.call(Time.now - request_start_time)
-        end
-
-        parser.feed(chunk, &block)
+        yielded_content = parse_and_route_chunk(parser, chunk, &block)
+        # Control messages are protocol bookkeeping, so they do not satisfy the slow-first-chunk marker.
+        record_first_chunk(request_start_time) if yielded_content
       end
       record_status(stream_response) unless @status_recorded
       parser.flush
@@ -199,6 +210,50 @@ module ReactOnRailsPro
       raise
     end
 
+    # Expected shapes from callers:
+    #   render_code_with_incremental_updates => { pull_result: true, response:, emitter: }
+    #   render_code_as_stream                => bare response object (pre-pull mode)
+    def normalize_executor_result(result)
+      # Incremental rendering returns a named result so unrelated Array-like responses are never
+      # mistaken for [response, emitter]. Older renderers still return only response. The
+      # :pull_result key is the protocol discriminator, so future response-shaped hashes are safe.
+      return result.values_at(:response, :emitter) if result.is_a?(Hash) && result.key?(:pull_result)
+
+      [result, nil]
+    end
+
+    def record_first_chunk(request_start_time)
+      return if @received_first_chunk
+
+      @received_first_chunk = true
+      @first_chunk_warn_callback&.call(Time.now - request_start_time)
+    end
+
+    def parse_and_route_chunk(parser, chunk, &)
+      yielded_content = false
+      parser.feed(chunk) do |parsed|
+        next route_control_message(parsed) if CONTROL_MESSAGE_TYPES.include?(parsed["messageType"])
+
+        yield parsed
+        yielded_content = true
+      end
+      yielded_content
+    end
+
+    def route_control_message(parsed)
+      return unless @emitter
+
+      case parsed["messageType"]
+      when "propRequest"
+        prop_name = parsed["propName"]
+        @emitter.pull_requests&.enqueue(prop_name) if prop_name.is_a?(String) &&
+                                                      !prop_name.empty? &&
+                                                      prop_name.length <= MAX_PULL_PROP_NAME_LENGTH
+      when "renderComplete"
+        @emitter.render_complete!
+      end
+    end
+
     # Retrying after first chunk would duplicate content in the page.
     def raise_or_retry_streaming_transport_error(error, available_retries)
       error_type = error.is_a?(ReactOnRailsPro::RendererHttpClient::TimeoutError) ? "Time out" : "Connection"

data/lib/react_on_rails_pro/version.rb

@@ -14,6 +14,6 @@
 # https://github.com/shakacode/react_on_rails/blob/main/REACT-ON-RAILS-PRO-LICENSE.md
 
 module ReactOnRailsPro
-  VERSION = "17.0.0.rc.4"
+  VERSION = "17.0.0.rc.6"
   PROTOCOL_VERSION = "2.0.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: react_on_rails_pro
 version: !ruby/object:Gem::Version
-  version: 17.0.0.rc.4
+  version: 17.0.0.rc.6
 platform: ruby
 authors:
 - Justin Gordon
@@ -119,14 +119,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 17.0.0.rc.4
+        version: 17.0.0.rc.6
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 17.0.0.rc.4
+        version: 17.0.0.rc.6
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement