docs: tighten renderer tuning guidance

Author: justin808

docs/oss/configuration/configuration-pro.md

@@ -101,7 +101,7 @@ ReactOnRailsPro.configure do |config|
   # Under standard Puma streaming, `Sync {}` creates a per-request scheduler and the client is
   # cleaned up when that response ends; the limit still applies within the streaming request.
   # Without a scheduler (non-streaming paths), a client is created per request. See
-  # "Renderer performance tuning for streamed RSC" below.
+  # "Renderer Performance Tuning for Streamed RSC" below.
   # Default for `renderer_http_pool_size` is 10
   config.renderer_http_pool_size = 10
 
@@ -202,15 +202,15 @@ Guidance:
 
 - Keep `renderer_http_pool_size` close to (and generally not far above) `workersCount`; sending many more concurrent streams than there are workers just queues renders at the renderer.
 - Account for your Rails concurrency: with many Puma threads/workers all streaming, a renderer with only one or two workers becomes the bottleneck. Scale `workersCount` (and renderer replicas) to your real concurrent streamed-render load.
-- Raise `ssr_timeout` for long-running streamed responses — it is the per-read socket timeout for the streaming connection.
+- Raise `ssr_timeout` for long-running streamed responses — it is the socket idle timeout for the streaming connection. It fires when the renderer sends no data for `ssr_timeout` seconds, not when the total response duration exceeds that value.
 
 ### 3. Rails ↔ renderer keep-alive (already on for streaming)
 
 Connection reuse is automatic when the renderer request runs under a long-lived `Fiber.scheduler`, such as Falcon or Puma configured with an async scheduler. In that setup, the async-http client is stored on the scheduler and reused across streaming requests, so HTTP/2 connections stay alive and renders multiplex over them instead of paying TCP/TLS setup per request (issue #3283). No React on Rails configuration is required to enable this.
 
 Under standard Puma, the streaming helper's `Sync {}` block creates a per-request scheduler. The async-http client is cleaned up when that streaming response ends, so connection reuse does not persist across consecutive Rails requests. The benefit is still meaningful inside a single streamed response: renderer calls in that response can share the same client lifecycle and `renderer_http_pool_size` still bounds concurrent HTTP/2 streams.
 
-`config.renderer_http_keep_alive_timeout` is **deprecated** and ignored: the async-http adapter manages connection lifecycle automatically (connections are reused within the scheduler and cleaned up when it ends). Setting it only logs a deprecation warning.
+`config.renderer_http_keep_alive_timeout` is **deprecated** and ignored: the async-http adapter manages connection lifecycle automatically (connections are reused within the scheduler and cleaned up when it ends). Setting it to a non-`nil` value logs a deprecation warning; setting it to `nil` is silent.
 
 To confirm reuse, compare before/after `responseEnd` timing and streamed RSC performance marks, and trace renderer sockets when you need to distinguish long-lived scheduler reuse from standard Puma's per-request scheduler cleanup.
 

llms-full.txt

@@ -18102,7 +18102,7 @@ ReactOnRailsPro.configure do |config|
   # Under standard Puma streaming, `Sync {}` creates a per-request scheduler and the client is
   # cleaned up when that response ends; the limit still applies within the streaming request.
   # Without a scheduler (non-streaming paths), a client is created per request. See
-  # "Renderer performance tuning for streamed RSC" below.
+  # "Renderer Performance Tuning for Streamed RSC" below.
   # Default for `renderer_http_pool_size` is 10
   config.renderer_http_pool_size = 10
 
@@ -18203,15 +18203,15 @@ Guidance:
 
 - Keep `renderer_http_pool_size` close to (and generally not far above) `workersCount`; sending many more concurrent streams than there are workers just queues renders at the renderer.
 - Account for your Rails concurrency: with many Puma threads/workers all streaming, a renderer with only one or two workers becomes the bottleneck. Scale `workersCount` (and renderer replicas) to your real concurrent streamed-render load.
-- Raise `ssr_timeout` for long-running streamed responses — it is the per-read socket timeout for the streaming connection.
+- Raise `ssr_timeout` for long-running streamed responses — it is the socket idle timeout for the streaming connection. It fires when the renderer sends no data for `ssr_timeout` seconds, not when the total response duration exceeds that value.
 
 ### 3. Rails ↔ renderer keep-alive (already on for streaming)
 
 Connection reuse is automatic when the renderer request runs under a long-lived `Fiber.scheduler`, such as Falcon or Puma configured with an async scheduler. In that setup, the async-http client is stored on the scheduler and reused across streaming requests, so HTTP/2 connections stay alive and renders multiplex over them instead of paying TCP/TLS setup per request (issue #3283). No React on Rails configuration is required to enable this.
 
 Under standard Puma, the streaming helper's `Sync {}` block creates a per-request scheduler. The async-http client is cleaned up when that streaming response ends, so connection reuse does not persist across consecutive Rails requests. The benefit is still meaningful inside a single streamed response: renderer calls in that response can share the same client lifecycle and `renderer_http_pool_size` still bounds concurrent HTTP/2 streams.
 
-`config.renderer_http_keep_alive_timeout` is **deprecated** and ignored: the async-http adapter manages connection lifecycle automatically (connections are reused within the scheduler and cleaned up when it ends). Setting it only logs a deprecation warning.
+`config.renderer_http_keep_alive_timeout` is **deprecated** and ignored: the async-http adapter manages connection lifecycle automatically (connections are reused within the scheduler and cleaned up when it ends). Setting it to a non-`nil` value logs a deprecation warning; setting it to `nil` is silent.
 
 To confirm reuse, compare before/after `responseEnd` timing and streamed RSC performance marks, and trace renderer sockets when you need to distinguish long-lived scheduler reuse from standard Puma's per-request scheduler cleanup.