Fix Content-Length mismatch and null renderingRequest errors in node renderer (#3069)

Fixes #3071

## Problem

Two related errors appear in production node renderer logs:

### Error 1: `FST_ERR_CTP_INVALID_CONTENT_LENGTH`

```json
{
  "level": "error",
  "msg": "Unhandled Fastify error",
  "err": {
    "code": "FST_ERR_CTP_INVALID_CONTENT_LENGTH",
    "message": "Request body size did not match Content-Length",
    "statusCode": 400
  }
}
```

### Error 2: `INVALID NIL or NULL result for rendering`

```json
{
  "level": "error",
  "msg": "INVALID result for prepareResult\n\nJS code for rendering request was:\nnull\n\nEXCEPTION MESSAGE:\nINVALID NIL or NULL result for rendering"
}
```

## Root Cause Analysis

These two errors are causally linked — Error 1 triggers Error 2.

### How the render request normally works

1. The Ruby gem sends an HTTP/2 POST to the node renderer with a
multipart form body containing `renderingRequest` (the JavaScript code
to execute in the SSR VM), optional bundle files, and metadata fields
2. Fastify's multipart parser reads the body, validates that the
received bytes match the `Content-Length` header, and attaches parsed
fields to `req.body`
3. The render handler extracts `req.body.renderingRequest` and passes it
to the VM for server-side rendering

### What goes wrong

The Ruby gem uses HTTPX with persistent HTTP/2 connections to the node
renderer. HTTP/2 connections are long-lived and multiplexed, but they
can become **stale** — the node renderer may close its end of the
connection (due to idle timeout, restart, or resource pressure) while
the Ruby side still considers it active.

When the Ruby gem writes a render request into a stale connection:

1. The connection may accept only part of the request body before the
transport layer detects the broken connection
2. The node renderer receives a **truncated body** — fewer bytes than
the `Content-Length` header promised
3. Fastify's body parser detects the mismatch and throws
`FST_ERR_CTP_INVALID_CONTENT_LENGTH` (Error 1)
4. Because the parser aborted, the multipart fields were never fully
parsed — `renderingRequest` is never attached to `req.body`
5. The render handler receives `req.body.renderingRequest` as
`undefined`/`null`, which propagates into `prepareResult()` →
`runInVM(null, ...)` → the VM returns null → "INVALID NIL or NULL result
for rendering" (Error 2)

The confusing part for operators is that Error 2 looks like a
JavaScript/rendering bug ("JS code for rendering request was: null"),
when the real problem is a transport-layer issue that happened before
any JavaScript executed.

## Changes

### 1. Prevent stale connections (root cause fix)

**Ruby gem** (`request.rb`, `configuration.rb`): Add
`keep_alive_timeout` (default: 30s) to the HTTPX persistent connection
configuration. This tells HTTPX to close idle connections after 30
seconds, preventing the Ruby side from writing into connections that the
node renderer has already closed. Configurable via
`renderer_http_keep_alive_timeout` with validation (must be a positive
number or nil).

### 2. Early validation with actionable diagnostics (defense in depth)

**Node renderer** (`worker.ts`): Validate `renderingRequest` immediately
after body parsing, before entering the render pipeline. When the field
is missing, null, or empty, the renderer now returns a descriptive 400
error instead of letting null propagate through the VM:

```
Invalid "renderingRequest" field in render request.
Expected a non-empty string of JavaScript to execute in the SSR VM.
Received type: null.
Received body keys: gemVersion, protocolVersion, railsEnv.
Likely causes: request body truncation, malformed multipart form data, or Content-Length mismatch in a proxy/client.
```

This gives operators immediate insight into what happened and where to
look, rather than the misleading "INVALID NIL or NULL result for
rendering" message.

### 3. Specific Content-Length mismatch logging

**Node renderer** (`worker.ts`): The Fastify `onError` hook now detects
`FST_ERR_CTP_INVALID_CONTENT_LENGTH` specifically and logs it as
"Invalid request body framing" with an actionable hint about
client/proxy truncation, rather than the generic "Unhandled Fastify
error" message.

### 4. Security: expanded sensitive key filtering

**Node renderer** (`worker.ts`): The diagnostic message includes body
keys to help debugging, but filters out sensitive field names. Expanded
from just `password` to also filter `token`, `secret`, `api_key`,
`auth_token`, `authorization`, and `credentials` — since these
diagnostics flow through error reporters (Sentry, Honeybadger).

## Test plan

- [x] Node renderer worker tests pass (23/23), including new tests for
missing, null, and empty-string `renderingRequest`, and expanded
sensitive key filtering
- [x] Pro gem configuration spec passes (46/46), including 6 new tests
for `renderer_http_keep_alive_timeout` validation
- [x] RuboCop passes on all changed files
- [x] ESLint and Prettier pass on all changed files
- [ ] CI

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Touches the Rails↔Node renderer transport configuration (HTTPX
timeouts) and request validation/logging, which can affect SSR
reliability and performance if misconfigured, but is scoped and covered
by tests.
> 
> **Overview**
> Fixes SSR failures caused by stale persistent connections by adding a
new Ruby config `renderer_http_keep_alive_timeout` (default `30`) and
wiring it into HTTPX `keep_alive_timeout` (with validation and improved
connection error context).
> 
> Hardens the Node renderer against truncated/malformed multipart bodies
by returning an actionable `400` when `renderingRequest` is
missing/null/empty/array, refining the reported type for empty strings,
and filtering additional sensitive body keys (including `credentials`)
from diagnostics; corresponding tests are updated/added.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
818020c. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added configurable HTTP keep-alive timeout for Node renderer
connections (default: 30s); accepts positive numbers or nil.

* **Bug Fixes**
* Clarified invalid rendering-request diagnostics — empty-string inputs
now reported as "empty string" for received-type messaging.

* **Tests**
* Added tests for keep-alive timeout validation and updated expectation
for empty-string rendering-request diagnostics.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: justin808

packages/react-on-rails-pro-node-renderer/src/worker.ts

@@ -174,15 +174,18 @@ const SENSITIVE_REQUEST_BODY_KEYS = new Set([
   'access_token',
   'accesstoken',
   'bearer',
+  'credentials',
 ]);
 
 const invalidRenderingRequestMessage = (body: Record<string, unknown>) => {
   const { renderingRequest } = body;
-  let renderingRequestType: string = renderingRequest === '' ? 'string (empty)' : typeof renderingRequest;
+  let renderingRequestType: string = typeof renderingRequest;
   if (renderingRequest === null) {
     renderingRequestType = 'null';
   } else if (Array.isArray(renderingRequest)) {
     renderingRequestType = 'array';
+  } else if (renderingRequest === '') {
+    renderingRequestType = 'empty string';
   }
   const bodyKeys = Object.keys(body).filter((key) => !SENSITIVE_REQUEST_BODY_KEYS.has(key.toLowerCase()));
 

packages/react-on-rails-pro-node-renderer/tests/worker.test.ts

@@ -193,7 +193,7 @@ describe('worker', () => {
 
     expect(res.statusCode).toBe(400);
     expect(res.payload).toContain('Invalid "renderingRequest" field in render request.');
-    expect(res.payload).toContain('Received type: string (empty).');
+    expect(res.payload).toContain('Received type: empty string.');
     expect(res.payload).toContain('Likely causes: request body truncation');
   });
 

react_on_rails_pro/lib/react_on_rails_pro/configuration.rb

@@ -15,6 +15,7 @@ def self.configuration
       renderer_http_pool_size: Configuration::DEFAULT_RENDERER_HTTP_POOL_SIZE,
       renderer_http_pool_timeout: Configuration::DEFAULT_RENDERER_HTTP_POOL_TIMEOUT,
       renderer_http_pool_warn_timeout: Configuration::DEFAULT_RENDERER_HTTP_POOL_WARN_TIMEOUT,
+      renderer_http_keep_alive_timeout: Configuration::DEFAULT_RENDERER_HTTP_KEEP_ALIVE_TIMEOUT,
       renderer_password: nil,
       tracing: Configuration::DEFAULT_TRACING,
       dependency_globs: Configuration::DEFAULT_DEPENDENCY_GLOBS,
@@ -44,6 +45,7 @@ class Configuration # rubocop:disable Metrics/ClassLength
     DEFAULT_RENDERER_HTTP_POOL_SIZE = 10
     DEFAULT_RENDERER_HTTP_POOL_TIMEOUT = 5
     DEFAULT_RENDERER_HTTP_POOL_WARN_TIMEOUT = 0.25
+    DEFAULT_RENDERER_HTTP_KEEP_ALIVE_TIMEOUT = 30
     DEFAULT_SSR_TIMEOUT = 5
     DEFAULT_PRERENDER_CACHING = false
     DEFAULT_TRACING = false
@@ -72,7 +74,7 @@ class Configuration # rubocop:disable Metrics/ClassLength
                   :rsc_payload_generation_url_path, :rsc_bundle_js_file, :react_client_manifest_file,
                   :react_server_client_manifest_file
 
-    attr_reader :concurrent_component_streaming_buffer_size
+    attr_reader :concurrent_component_streaming_buffer_size, :renderer_http_keep_alive_timeout
 
     # Sets the buffer size for concurrent component streaming.
     #
@@ -91,10 +93,23 @@ def concurrent_component_streaming_buffer_size=(value)
       @concurrent_component_streaming_buffer_size = value
     end
 
+    # Sets the keep-alive timeout (in seconds) for persistent HTTP connections to the node renderer.
+    #
+    # @param value [Numeric, nil] A positive number or nil (to use the HTTPX default)
+    # @raise [ReactOnRailsPro::Error] if value is not a positive number or nil
+    def renderer_http_keep_alive_timeout=(value)
+      unless value.nil? || (value.is_a?(Numeric) && value.positive? && value.finite?)
+        raise ReactOnRailsPro::Error,
+              "config.renderer_http_keep_alive_timeout must be a finite positive number or nil"
+      end
+      @renderer_http_keep_alive_timeout = value
+    end
+
     def initialize(renderer_url: nil, renderer_password: nil, server_renderer: nil, # rubocop:disable Metrics/AbcSize
                    renderer_use_fallback_exec_js: nil, prerender_caching: nil,
                    renderer_http_pool_size: nil, renderer_http_pool_timeout: nil,
-                   renderer_http_pool_warn_timeout: nil, tracing: nil,
+                   renderer_http_pool_warn_timeout: nil, renderer_http_keep_alive_timeout: nil,
+                   tracing: nil,
                    dependency_globs: nil, excluded_dependency_globs: nil, rendering_returns_promises: nil,
                    remote_bundle_cache_adapter: nil, ssr_pre_hook_js: nil, assets_to_copy: nil,
                    renderer_request_retry_limit: nil, throw_js_errors: nil, ssr_timeout: nil,
@@ -111,6 +126,7 @@ def initialize(renderer_url: nil, renderer_password: nil, server_renderer: nil,
       self.renderer_http_pool_size = renderer_http_pool_size
       self.renderer_http_pool_timeout = renderer_http_pool_timeout
       self.renderer_http_pool_warn_timeout = renderer_http_pool_warn_timeout
+      self.renderer_http_keep_alive_timeout = renderer_http_keep_alive_timeout
       self.tracing = tracing
       self.rendering_returns_promises = server_renderer == "NodeRenderer" ? rendering_returns_promises : false
       self.dependency_globs = dependency_globs

react_on_rails_pro/lib/react_on_rails_pro/request.rb

@@ -422,18 +422,19 @@ def create_connection # rubocop:disable Metrics/MethodLength, Metrics/AbcSize
             # :write_timeout
             # :request_timeout
             # :operation_timeout
-            # :keep_alive_timeout
             timeout: {
               connect_timeout: ReactOnRailsPro.configuration.renderer_http_pool_timeout,
-              read_timeout: ReactOnRailsPro.configuration.ssr_timeout
-            }
+              read_timeout: ReactOnRailsPro.configuration.ssr_timeout,
+              keep_alive_timeout: ReactOnRailsPro.configuration.renderer_http_keep_alive_timeout
+            }.compact
           )
       rescue StandardError => e
         message = <<~MSG
           [ReactOnRailsPro] Error creating HTTPX connection.
           renderer_http_pool_size = #{ReactOnRailsPro.configuration.renderer_http_pool_size}
           renderer_http_pool_timeout = #{ReactOnRailsPro.configuration.renderer_http_pool_timeout}
           renderer_http_pool_warn_timeout = #{ReactOnRailsPro.configuration.renderer_http_pool_warn_timeout}
+          renderer_http_keep_alive_timeout = #{ReactOnRailsPro.configuration.renderer_http_keep_alive_timeout}
           renderer_url = #{url}
           Be sure to use a url that contains the protocol of http or https.
           Original error is

react_on_rails_pro/spec/dummy/spec/requests/upload_asset_spec.rb

@@ -20,6 +20,7 @@
                                         renderer_http_pool_size: 1,
                                         renderer_http_pool_timeout: 5,
                                         renderer_http_pool_warn_timeout: 0.25,
+                                        renderer_http_keep_alive_timeout: 30,
                                         renderer_request_retry_limit: 5,
                                         ssr_timeout: 5,
                                         assets_to_copy: [

react_on_rails_pro/spec/react_on_rails_pro/configuration_spec.rb

@@ -429,6 +429,66 @@ def self.fetch(*)
       end
     end
 
+    describe ".renderer_http_keep_alive_timeout" do
+      it "defaults to 30" do
+        ReactOnRailsPro.configure {} # rubocop:disable Lint/EmptyBlock
+
+        expect(ReactOnRailsPro.configuration.renderer_http_keep_alive_timeout).to eq(30)
+      end
+
+      it "accepts positive numbers" do
+        ReactOnRailsPro.configure do |config|
+          config.renderer_http_keep_alive_timeout = 60
+        end
+
+        expect(ReactOnRailsPro.configuration.renderer_http_keep_alive_timeout).to eq(60)
+      end
+
+      it "accepts nil" do
+        ReactOnRailsPro.configure do |config|
+          config.renderer_http_keep_alive_timeout = nil
+        end
+
+        expect(ReactOnRailsPro.configuration.renderer_http_keep_alive_timeout).to be_nil
+      end
+
+      it "raises error for zero" do
+        expect do
+          ReactOnRailsPro.configure do |config|
+            config.renderer_http_keep_alive_timeout = 0
+          end
+        end.to raise_error(ReactOnRailsPro::Error,
+                           /must be a finite positive number or nil/)
+      end
+
+      it "raises error for negative numbers" do
+        expect do
+          ReactOnRailsPro.configure do |config|
+            config.renderer_http_keep_alive_timeout = -5
+          end
+        end.to raise_error(ReactOnRailsPro::Error,
+                           /must be a finite positive number or nil/)
+      end
+
+      it "raises error for non-numeric values" do
+        expect do
+          ReactOnRailsPro.configure do |config|
+            config.renderer_http_keep_alive_timeout = "30"
+          end
+        end.to raise_error(ReactOnRailsPro::Error,
+                           /must be a finite positive number or nil/)
+      end
+
+      it "raises error for infinite values" do
+        expect do
+          ReactOnRailsPro.configure do |config|
+            config.renderer_http_keep_alive_timeout = Float::INFINITY
+          end
+        end.to raise_error(ReactOnRailsPro::Error,
+                           /must be a finite positive number or nil/)
+      end
+    end
+
     describe ".concurrent_component_streaming_buffer_size" do
       it "accepts positive integers" do
         ReactOnRailsPro.configure do |config|