universal_renderer 0.2.4 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 744a98174d956b133ed9cfb4cdaa9fe931dcc5f4ddd0797797aeb201ace4f387
-  data.tar.gz: 11ebab458200137d7ff996f11a2263854c2c62ef16ce8053f213045b96c374a5
+  metadata.gz: 61b47ecd00a6c6401d0689b67cf9944859c43e8f1f0cbae343c7b9f0865e5dc7
+  data.tar.gz: 96221231e4c6c3293c1c3b9c36fa0c2c338967703582262113781cec2cdd1336
 SHA512:
-  metadata.gz: 9dd89b2e34c3c227ef792a4443c4eb6b93128542c3d409cafd5a78451e0863ae470636ef940062e77fdd423e18f03880d5e64214381c3b714fea99af5d7b1bc5
-  data.tar.gz: 99006bff1b47f731a57b58bc7700553c13a364977dd4a9bba7d72f034c1b9725821e375d69973d868c12ce3bccc1cb3e078d29d0314ef1548cac52c821d5f37e
+  metadata.gz: 3a524d63eb673564622aa1329fc8c9ff8b47ea131f0785c79caf9a75e60f12912228f0f74dd7a44fe6a1958932f8514d214b539f3a32f7c62cf63d76b695669b
+  data.tar.gz: a423a79cc5e0d39ba58b039c7eec0d40b804625bc98e71bbeb57fe233b236f62794295daf6335efc5fd5d1ac1ae31cc19443ff10423c82b251360e5a4fa88bdf

data/README.md

@@ -1,268 +1,246 @@
 # UniversalRenderer
 
-UniversalRenderer provides a streamlined way to integrate Server-Side Rendering (SSR) with an external SSR service into your Rails application. It helps you forward rendering requests, manage static or streaming responses, and improve performance, SEO, and user experience for JavaScript-heavy frontends.
+A streamlined solution for integrating Server-Side Rendering (SSR) into Rails applications.
 
-## Features
-
-- Supports both static and streaming SSR.
-- Configurable SSR server endpoint and timeouts.
-- Helper methods for passing data to your SSR service.
-- Automatic fallback to client-side rendering if SSR fails.
-- View helpers for integrating SSR content into your layouts.
+## Overview
 
-## Installation
+UniversalRenderer helps you forward rendering requests to external SSR services, manage responses, and improve performance, SEO, and user experience for JavaScript-heavy frontends. It works seamlessly with the `universal-renderer` NPM package.
 
-1.  Add this line to your application's Gemfile:
+## Features
 
-    ```ruby
-    gem "universal_renderer"
-    ```
+- **Static and streaming SSR** support
+- **Configurable SSR server endpoint** and timeouts
+- **Simple API** for passing data between Rails and your SSR service
+- **Automatic fallback** to client-side rendering if SSR fails
+- **View helpers** for easy integration into your layouts
 
-2.  And then execute:
+## Installation
 
-    ```bash
-    $ bundle install
-    ```
+1. Add to your Gemfile:
 
-3.  Run the install generator to create an initializer and include the necessary concern in your `ApplicationController`:
+   ```ruby
+   gem "universal_renderer"
+   ```
 
-    ```bash
-    $ rails generate universal_renderer:install
-    ```
+2. Install:
 
-    This will:
+   ```bash
+   $ bundle install
+   ```
 
-    - Create `config/initializers/universal_renderer.rb`.
-    - Add `include UniversalRenderer::Rendering` to your `app/controllers/application_controller.rb`.
+3. Run the generator:
+   ```bash
+   $ rails generate universal_renderer:install
+   ```
 
 ## Configuration
 
-Configure UniversalRenderer in `config/initializers/universal_renderer.rb`:
+Configure in `config/initializers/universal_renderer.rb`:
 
 ```ruby
 UniversalRenderer.configure do |config|
-  # (Required) The base URL of your SSR server.
-  # Example: 'http://localhost:3001' or 'https://your-ssr-service.com'
-  # Can also be set via the SSR_SERVER_URL environment variable.
-  config.ssr_url = ENV.fetch("SSR_SERVER_URL", "http://localhost:3001")
-
-  # (Optional) Timeout in seconds for requests to the SSR server.
-  # Defaults to 3 seconds.
-  # Can also be set via the SSR_TIMEOUT environment variable.
-  config.timeout = (ENV["SSR_TIMEOUT"] || 3).to_i
-
-  # (Optional) The path on your SSR server for streaming requests.
-  # Defaults to '/stream'.
-  # Can also be set via the SSR_STREAM_PATH environment variable.
-  config.ssr_stream_path = ENV.fetch("SSR_STREAM_PATH", "/stream")
+  config.ssr_url = "http://localhost:3001"
 end
 ```
 
-**Environment Variables:**
-The `ssr_url`, `timeout`, and `ssr_stream_path` can be configured directly via environment variables (`SSR_SERVER_URL`, `SSR_TIMEOUT`, `SSR_STREAM_PATH`). If set, environment variables will take precedence over values in the initializer.
-
-## Usage
-
-The `universal_renderer:install` generator includes the `UniversalRenderer::Rendering` concern into your `ApplicationController`. This concern overrides `default_render` to automatically handle SSR.
-
-### Rendering Flow Details
-
-This gem facilitates communication with an external Node.js SSR server (like one built with the `universal-renderer` npm package).
-
-**1. Static Rendering Flow:**
-
-- When streaming is disabled or not applicable, the gem makes a `POST` request to the SSR server's static endpoint (by default, the root `/` of the `config.ssr_url`).
-- The request includes the current URL and any props added via `add_props`.
-- The SSR server is expected to return a JSON object (e.g., `{ "html_content": "...", "meta_tags": "...", "initial_state": { ... } }`).
-- This JSON response is made available in your Rails view (typically `app/views/ssr/index.html.erb`) as the `@ssr` instance variable (with symbolized keys, e.g., `@ssr[:html_content]`).
-
-**2. Streaming Rendering Flow:**
-
-- **Layout Rendering & Splitting**:
-  - Your Rails application (e.g., `app/views/layouts/application.html.erb`) begins to render. This layout **must** use the `<%= ssr_meta %>` helper at the point where SSR meta tags should be injected (usually late in the `<head>`) and `<%= ssr_body %>` where the main SSR application body should appear.
-  - The `Rendering` concern captures the full layout string. It then splits this string at the `<!-- SSR_META -->` comment (generated by `<%= ssr_meta %>`).
-  - The portion of the layout _before_ `<!-- SSR_META -->` is immediately written to the HTTP response stream and sent to the client.
-- **Request to SSR Server**:
-  - The gem then makes a `POST` request to the SSR server's streaming endpoint (configured by `config.ssr_stream_path`, default `/stream`).
-  - The JSON payload of this request includes:
-    - `url`: The current Rails request URL.
-    - `props`: Data passed from your Rails controller using `add_props`.
-    - `template`: This field contains the latter part of the rendered Rails view string, starting _directly with_ the `<!-- SSR_META -->` marker (generated by `<%= ssr_meta %>`) and continuing to the end of the document. This string must also include the `<!-- SSR_BODY -->` marker (generated by `<%= ssr_body %>`). The Node.js SSR server uses this `template` to construct the response around the streamed React application: it first sends the `<!-- SSR_META -->` part from the `template`, then injects its computed meta tags, then sends the HTML content found between `<!-- SSR_META -->` and `<!-- SSR_BODY -->` from the `template`. After this, the React application is streamed (filling the place of `<!-- SSR_BODY -->`), and finally, the portion of the `template` that was after `<!-- SSR_BODY -->` is appended.
-- **Streaming Response**:
-  - The Node.js SSR server streams HTML content back. This content is piped directly into the Rails response stream, filling the placeholders in the `template` it received.
-
-**Fallback:**
-If SSR (either static or streaming) fails in a way that allows for it, the system will typically fall back to rendering `app/views/application/index.html.erb`, which should contain your client-side rendering (CSR) entry point.
-
-### Passing Data to SSR (`add_props`)
-
-In your controllers, you can use the `add_props` method to pass data from your Rails application to the SSR service. This data will be available as a JSON object under the `props` key in the JSON payload sent to your SSR service.
-
-`add_props` can be called in two ways:
-
-1.  **Key-Value Pair:**
-
-    ```ruby
-    # In your controller action
-    def show
-      @product = Product.find(params[:id])
-      add_props(:product, @product.as_json) # Ensure data is serializable
-      add_props(:current_user_name, current_user.name)
-      # ... default_render will be called implicitly
-    end
-    ```
-
-    This will result in the `props` object in the SSR request payload being like:
-    `{ "product": { ...product_data... }, "current_user_name": "User Name" }`
-
-2.  **Hash Argument:**
-
-    ```ruby
-    # In your controller action
-    def index
-      @posts = Post.recent
-      add_props(posts: @posts.map(&:as_json), current_page: params[:page])
-      # ... default_render will be called implicitly
-    end
-    ```
-
-    This will result in the `props` object in the SSR request payload being like:
-    `{ "posts": [ ...posts_data... ], "current_page": "1" }`
+## Basic Usage
 
-Make sure any data passed is serializable to JSON (e.g., call `.as_json` on ActiveRecord objects).
+After installation, you can pass data to your SSR service using `add_prop` in your controllers:
 
-### Templates
-
-The gem relies on a few conventional template paths:
-
-- `app/views/ssr/index.html.erb`: Used when `StaticClient` successfully receives data from the SSR server. This template typically uses the data (available in `@ssr`) to render the page.
-  **Example (`app/views/ssr/index.html.erb` for static rendering):**
-  This example assumes your SSR server returns a JSON object with keys like `:meta`, `:styles`, `:root`, and `:state`. You would need to ensure proper sanitization of this content (e.g., using `sanitize` or a custom helper like `sanitize_ssr` shown below).
-
-  ```erb
-  <%# Assuming @ssr contains keys like :meta, :styles, :root, :state from the SSR server %>
-  <%# You are responsible for sanitizing these values appropriately. %>
-  <%# The sanitize_ssr helper is hypothetical and you'd need to implement it or use Rails' sanitize. %>
-
-  <% content_for :head_tags do %>
-    <%= raw @ssr[:meta] %> <%# Example: <meta name="description" content="..."> %>
-    <%= raw @ssr[:styles] %> <%# Example: <style>...</style> or <link rel="stylesheet" ...> %>
-  <% end %>
-
-  <div id="root" data-ssr-rendered="true">
-    <%= raw @ssr[:root] %> <%# Example: <div>Your pre-rendered React/Vue/etc. app</div> %>
-  </div>
-
-  <script id="ssr-state" type="application/json">
-    <%= raw @ssr[:state].to_json %>
-  </script>
-  ```
+```ruby
+class ProductsController < ApplicationController
+  enable_ssr # enables SSR controller-wide
 
-  Remember to yield `:head_tags` in your main layout's `<head>` section (e.g., `<%= yield :head_tags %>`) if you use `content_for` as in this example.
+  def show
+    @product = Product.find(params[:id])
 
-- `app/views/application/index.html.erb`: This template is used as a fallback if SSR fails (e.g., SSR server is down, returns an error, or `StaticClient` receives no data). This usually contains your client-side rendering (CSR) entry point.
+    # We can use the provided add_prop method to set a single value.
+    add_prop(:product, @product.as_json)
 
-### View Helpers (`SsrHelpers`)
+    # We can use the provided push_prop method to push multiple values to an array.
+    # This is useful for pushing data to React Query.
+    push_prop(:query_data, { key: ["currentUser"], data: current_user.as_json })
 
-The `UniversalRenderer::SsrHelpers` module provides helpers to mark locations in your HTML structure. For streaming to work correctly with a compatible Node.js SSR server (like `universal-renderer`), these helpers (or the raw HTML comments they produce) are crucial in your main Rails layout (e.g., `app/views/layouts/application.html.erb`).
+    fetch_ssr # or fetch on demand
 
-- `ssr_meta`: Placeholder for meta tags or other head elements generated by SSR. When used in a Rails layout for streaming, this helper outputs `<!-- SSR_META -->`, which the Node.js SSR server uses as an injection point.
-- `ssr_body`: Placeholder for the main root element where your SSR application will be rendered. When used in a Rails layout for streaming, this helper outputs `<!-- SSR_BODY -->`, which the Node.js SSR server uses to stream the main application content into.
+    # @ssr will now contain the SSR response, where the symbolized keys
+    # are the same keys returned by the SSR server response.
+  end
 
-**Example (`app/views/layouts/application.html.erb` for streaming):**
+  def default_render
+    # If you want to re-use the same layout across multiple actions.
+    # You can also put this in your ApplicationController.
+    render "ssr/index"
+  end
+end
+```
 
 ```erb
-<!DOCTYPE html>
-<html>
-<head>
-  <title>My App</title>
-  <%= csrf_meta_tags %>
-  <%= csp_meta_tag %>
-  <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
-  <%= ssr_meta %> <%# SSR service might inject specific meta tags here %>
-</head>
-<body>
-  <div id="root">
-    <%= ssr_body %> <%# SSR service streams the main application content here %>
-  </div>
-  <%= javascript_importmap_tags %>
-</body>
-</html>
-```
+<%# "ssr/index" %>
 
-## SSR Server Expectations
-
-Your external SSR server needs to meet the following expectations:
-
-1.  **Static Rendering Endpoint (for `StaticClient`):**
-
-    - **Path:** Root path (`/`) of the `config.ssr_url`.
-      _Note: Some Node.js SSR servers like `universal-renderer` might default to a `/static` path. Ensure your SSR server listens on `/` for static requests if using this gem's default, or configure the Node.js server's `basePath` or routes accordingly._
-    - **Method:** `POST`
-    - **Request Body (JSON):**
-      ```jsonc
-      {
-        "url": "current_rails_request_original_url",
-        "props": {
-          // JSON object built from add_props calls
-          // e.g., "product": { ... }, "current_user_name": "..."
-        },
-      }
-      ```
-    - **Successful Response:** `200 OK` with a JSON body. The structure of this JSON is up to you, but it will be available in your `app/views/ssr/index.html.erb` template as `@ssr` (with keys symbolized). Example:
-      ```jsonc
-      {
-        "meta": "<meta name='description' content='Pre-rendered page description'>\n<meta property='og:title' content='My SSR Page'>",
-        "styles": "<link rel='stylesheet' href='/path/to/ssr-specific-styles.css'>",
-        "root": "<div><h1>Hello from SSR!</h1><p>This is your pre-rendered application content.</p></div>",
-        "state": {
-          "productId": 123,
-          "initialData": { "foo": "bar" },
-        },
-      }
-      ```
-
-2.  **Streaming Rendering Endpoint (for `StreamClient`):**
-
-    - **Path:** `config.ssr_stream_path` (defaults to `/stream`) on the `config.ssr_url`.
-    - **Method:** `POST`
-    - **Request Body (JSON):**
-      ```jsonc
-      {
-        "url": "current_rails_request_original_url",
-        "props": {
-          // User-defined props from add_props calls,
-          // e.g., "product": { ... }, "current_user_name": "..."
-        },
-        "template": "<!-- SSR_META -->...HTML between meta and body...<!-- SSR_BODY -->...HTML after body...</html>",
-      }
-      ```
-    - **Successful Response:** `200 OK` with `Content-Type: text/html`. The body should be an HTML stream. The Node.js SSR server will use the `template` field from the request body to inject content at the `<!-- SSR_META -->` and `<!-- SSR_BODY -->` placeholders.
-
-## Example Controller
+<%# Now you can use the instance variable @ssr in your layout. %>
+<%# We'll send it with keys :meta, :styles, :root, and :state below. %>
+<%# We can use the provided sanitize_ssr helper to sanitize our content %>
 
-```ruby
-# app/controllers/products_controller.rb
-class ProductsController < ApplicationController
-  def show
-    @product = Product.find(params[:id])
+<% content_for :meta do %>
+  <%= sanitize_ssr @ssr[:meta] %>
+<% end %>
 
-    # Pass data to SSR service using add_props
-    add_props(
-      product: @product.as_json, # Ensure data is serializable
-      related_products: @product.related_products.limit(5).as_json,
-    )
+<div id="root">
+  <%= sanitize_ssr @ssr[:styles] %>
+  <%= sanitize_ssr @ssr[:root] %>
+</div>
 
-    # default_render (from UniversalRenderer::Rendering) will be called automatically,
-    # handling either streaming or static SSR based on configuration and environment.
-  end
-end
+<script id="state" type="application/json">
+  <%= json_escape(@ssr[:state].to_json) %>
+</script>
 ```
 
+## Setting Up the SSR Server
+
+To set up the SSR server for your Rails application:
+
+1. Install the NPM package in your JavaScript project:
+
+   ```bash
+   $ npm install universal-renderer
+   # or
+   $ yarn add universal-renderer
+   # or
+   $ bun add universal-renderer
+   ```
+
+2. Create a `setup` function at `app/frontend/ssr/setup.ts`:
+
+   ```tsx
+   import {
+     HelmetProvider,
+     type HelmetDataContext,
+   } from "@dr.pogodin/react-helmet";
+   import { dehydrate, QueryClient, QueryClientProvider } from "react-query";
+   import { StaticRouter } from "react-router";
+   import { ServerStyleSheet } from "styled-components";
+
+   import App from "@/App";
+   import Metadata from "@/components/Metadata";
+
+   export default function setup(url: string, props: any) {
+     const pathname = new URL(url).pathname;
+
+     const helmetContext: HelmetDataContext = {};
+     const sheet = new ServerStyleSheet();
+     const queryClient = new QueryClient();
+
+     const { query_data } = props;
+     query_data.forEach(({ key, data }) => queryClient.setQueryData(key, data));
+     const state = dehydrate(queryClient);
+
+     const jsx = sheet.collectStyles(
+       <HelmetProvider context={helmetContext}>
+         <Metadata url={url} />
+         <QueryClientProvider client={queryClient}>
+           <StaticRouter location={pathname}>
+             <App />
+           </StaticRouter>
+         </QueryClientProvider>
+       </HelmetProvider>,
+     );
+
+     return { jsx, helmetContext, sheet, state, queryClient };
+   }
+   ```
+
+3. Update your `application.tsx` to hydrate the SSR state:
+
+   ```tsx
+   import { HelmetProvider } from "@dr.pogodin/react-helmet";
+   import { createRoot, hydrateRoot } from "react-dom/client";
+   import { Hydrate, QueryClient, QueryClientProvider } from "react-query";
+   import { BrowserRouter } from "react-router";
+
+   import App from "@/App";
+   import Metadata from "@/components/Metadata";
+
+   const queryClient = new QueryClient();
+   const stateElement = document.getElementById("state")!;
+   const state = JSON.parse(stateElement.textContent);
+
+   const app = (
+     <HelmetProvider>
+       <Metadata url={window.location.href} />
+       <QueryClientProvider client={queryClient}>
+         <Hydrate state={state}>
+           <BrowserRouter>
+             <App />
+           </BrowserRouter>
+         </Hydrate>
+       </QueryClientProvider>
+     </HelmetProvider>
+   );
+
+   const rootElement = document.getElementById("root")!;
+   hydrateRoot(rootElement, app);
+   ```
+
+4. Create an SSR entry point at `app/frontend/ssr/ssr.ts`:
+
+   ```ts
+   import { renderToString } from "react-dom/server";
+   import { createSsrServer } from "universal-renderer";
+   import { createServer as createViteServer } from "vite";
+
+   import setup from "@/ssr/setup";
+
+   const vite = await createViteServer({
+     server: { middlewareMode: true },
+     appType: "custom",
+   });
+
+   const app = await createSsrServer({
+     vite,
+     callbacks: {
+       // as typeof is a little hack to get the types to resolve correctly
+       // since Vite's ssrLoadModule doesn't include the types
+       setup: (await vite.ssrLoadModule("@/ssr/setup")).default as typeof setup,
+       render: async ({ jsx, helmetContext, sheet, state }) => {
+         const root = renderToString(jsx);
+         const meta = extractMeta(helmetContext);
+         const styles = sheet.getStyleTags();
+         return { meta, root, styles, state };
+       },
+       cleanup: async ({ sheet, queryClient }) => {
+         sheet?.seal();
+         queryClient?.clear();
+       },
+       onError: (error, context, errorContext) => {
+         vite.ssrFixStacktrace(error);
+         console.error(error);
+       },
+     },
+   });
+
+   app.listen(3001, () => {
+     console.log(`[SSR] server started on http://localhost:3001`);
+   });
+   ```
+
+5. Build the SSR bundle:
+
+   ```bash
+   $ bin/vite build --ssr
+   ```
+
+6. Start your servers:
+
+   ```Procfile
+   web: bin/rails s
+   ssr: bin/vite ssr
+   ```
+
 ## Contributing
 
-TODO
+Contributions are welcome! Please follow the coding guidelines in the project documentation.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+Available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/generators/universal_renderer/install_generator.rb

@@ -5,13 +5,5 @@ module UniversalRenderer
     def copy_initializer
       template "initializer.rb", "config/initializers/universal_renderer.rb"
     end
-
-    def include_concern
-      application_controller = "app/controllers/application_controller.rb"
-
-      inject_into_class application_controller,
-                        "ApplicationController",
-                        "  include UniversalRenderer::Rendering\n"
-    end
   end
 end

data/lib/universal_renderer/client/base.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module UniversalRenderer
+  module Client
+    # Fetches server-side rendered (SSR) content from the Node.js service
+    # in a single, blocking request. This client is used when SSR content
+    # is needed in its entirety before the Rails view rendering proceeds,
+    # as opposed to streaming SSR.
+    class Base
+      class << self
+        # Performs a POST request to the SSR service to retrieve the complete SSR content.
+        # This is used for non-streaming SSR, where the entire payload is fetched
+        # before the main application view is rendered.
+        #
+        # @param url [String] The URL of the page to render on the SSR server.
+        #   This should typically be the `request.original_url` from the controller.
+        # @param props [Hash] A hash of props to be passed to the SSR service.
+        #   These props will be available to the frontend components for rendering.
+        # @return [Hash, nil] The parsed JSON response from the SSR service with symbolized keys
+        #   if the request is successful (HTTP 2xx). The structure of the hash depends
+        #   on the SSR service implementation but typically includes keys like `:head`,
+        #   `:body_html`, and `:body_attrs`.
+        #   Returns `nil` if:
+        #   - The `ssr_url` is not configured.
+        #   - The request times out (open or read).
+        #   - The SSR service returns a non-successful HTTP status code.
+        #   - Any other `StandardError` occurs during the request.
+        #   In case of failures, an error message is logged to `Rails.logger`.
+        def fetch(url, props)
+          ssr_url = UniversalRenderer.config.ssr_url
+          return if ssr_url.blank?
+
+          timeout = UniversalRenderer.config.timeout
+
+          begin
+            uri = URI.parse(ssr_url)
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = (uri.scheme == "https")
+            http.open_timeout = timeout
+            http.read_timeout = timeout
+
+            request = Net::HTTP::Post.new(uri.request_uri)
+            request.body = { url: url, props: props }.to_json
+            request["Content-Type"] = "application/json"
+
+            response = http.request(request)
+
+            if response.is_a?(Net::HTTPSuccess)
+              JSON.parse(response.body).deep_symbolize_keys
+            else
+              Rails.logger.error(
+                "SSR fetch request to #{ssr_url} failed: #{response.code} - #{response.message} (URL: #{url})"
+              )
+              nil
+            end
+          rescue Net::OpenTimeout, Net::ReadTimeout => e
+            Rails.logger.error(
+              "SSR fetch request to #{ssr_url} timed out: #{e.class.name} - #{e.message} (URL: #{url})"
+            )
+            nil
+          rescue StandardError => e
+            Rails.logger.error(
+              "SSR fetch request to #{ssr_url} failed: #{e.class.name} - #{e.message} (URL: #{url})"
+            )
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/universal_renderer/client/stream/error_logger.rb

@@ -0,0 +1,31 @@
+module UniversalRenderer
+  module Client
+    class Stream
+      module ErrorLogger
+        class << self
+          def _log_setup_error(error, target_uri_string)
+            backtrace_info = error.backtrace&.first || "No backtrace available"
+            Rails.logger.error(
+              "Unexpected error during SSR stream setup for #{target_uri_string}: " \
+                "#{error.class.name} - #{error.message} at #{backtrace_info}"
+            )
+          end
+
+          def _log_connection_error(error, target_uri_string)
+            Rails.logger.error(
+              "SSR stream connection to #{target_uri_string} failed: #{error.class.name} - #{error.message}"
+            )
+          end
+
+          def _log_unexpected_error(error, target_uri_string, context_message)
+            backtrace_info = error.backtrace&.first || "No backtrace available"
+            Rails.logger.error(
+              "#{context_message} for #{target_uri_string}: " \
+                "#{error.class.name} - #{error.message} at #{backtrace_info}"
+            )
+          end
+        end
+      end
+    end
+  end
+end