universal_renderer 0.2.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 744a98174d956b133ed9cfb4cdaa9fe931dcc5f4ddd0797797aeb201ace4f387
+  data.tar.gz: 11ebab458200137d7ff996f11a2263854c2c62ef16ce8053f213045b96c374a5
+SHA512:
+  metadata.gz: 9dd89b2e34c3c227ef792a4443c4eb6b93128542c3d409cafd5a78451e0863ae470636ef940062e77fdd423e18f03880d5e64214381c3b714fea99af5d7b1bc5
+  data.tar.gz: 99006bff1b47f731a57b58bc7700553c13a364977dd4a9bba7d72f034c1b9725821e375d69973d868c12ce3bccc1cb3e078d29d0314ef1548cac52c821d5f37e

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright thaske
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,268 @@
+# 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.
+
+## 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.
+
+## Installation
+
+1.  Add this line to your application's Gemfile:
+
+    ```ruby
+    gem "universal_renderer"
+    ```
+
+2.  And then execute:
+
+    ```bash
+    $ bundle install
+    ```
+
+3.  Run the install generator to create an initializer and include the necessary concern in your `ApplicationController`:
+
+    ```bash
+    $ rails generate universal_renderer:install
+    ```
+
+    This will:
+
+    - Create `config/initializers/universal_renderer.rb`.
+    - Add `include UniversalRenderer::Rendering` to your `app/controllers/application_controller.rb`.
+
+## Configuration
+
+Configure UniversalRenderer 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")
+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" }`
+
+Make sure any data passed is serializable to JSON (e.g., call `.as_json` on ActiveRecord objects).
+
+### 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>
+  ```
+
+  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.
+
+- `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.
+
+### View Helpers (`SsrHelpers`)
+
+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`).
+
+- `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.
+
+**Example (`app/views/layouts/application.html.erb` for streaming):**
+
+```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 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
+
+```ruby
+# app/controllers/products_controller.rb
+class ProductsController < ApplicationController
+  def show
+    @product = Product.find(params[:id])
+
+    # 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,
+    )
+
+    # default_render (from UniversalRenderer::Rendering) will be called automatically,
+    # handling either streaming or static SSR based on configuration and environment.
+  end
+end
+```
+
+## Contributing
+
+TODO
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/controllers/concerns/universal_renderer/rendering.rb

@@ -0,0 +1,132 @@
+module UniversalRenderer
+  module Rendering
+    extend ActiveSupport::Concern
+
+    included do
+      include ActionController::Live
+      helper UniversalRenderer::SsrHelpers
+      before_action :initialize_props
+    end
+
+    private
+
+    def default_render
+      return super unless request.format.html?
+      if use_ssr_streaming?
+        render_ssr_stream
+      else
+        @ssr =
+          UniversalRenderer::StaticClient.static(
+            request.original_url,
+            @universal_renderer_props
+          )
+        super
+      end
+    end
+
+    def render_ssr_stream
+      set_streaming_headers
+
+      full_layout = render_to_string
+
+      split_index = full_layout.index("<!-- SSR_META -->")
+      before_meta = full_layout[0...split_index]
+      after_meta = full_layout[split_index..]
+
+      response.stream.write(before_meta)
+
+      current_props = @universal_renderer_props.dup
+
+      streaming_succeeded =
+        UniversalRenderer::StreamClient.stream(
+          request.original_url,
+          current_props,
+          after_meta,
+          response
+        )
+
+      handle_ssr_stream_fallback(response) unless streaming_succeeded
+    end
+
+    def initialize_props
+      @universal_renderer_props = {}
+    end
+
+    def add_props(key_or_hash, data_value = nil)
+      if data_value.nil? && key_or_hash.is_a?(Hash)
+        @universal_renderer_props.merge!(key_or_hash.deep_stringify_keys)
+      else
+        @universal_renderer_props[key_or_hash.to_s] = data_value
+      end
+    end
+
+    # Allows a prop to be treated as an array, pushing new values to it.
+    # If the prop does not exist or is nil, it's initialized as an array.
+    # If the prop exists but is not an array (e.g., set as a scalar by `add_props`),
+    # its current value will be converted into the first element of the new array.
+    # If `value_to_add` is an array, its elements are concatenated. Otherwise, `value_to_add` is appended.
+    def push_prop(key, value_to_add)
+      prop_key = key.to_s
+      current_value = @universal_renderer_props[prop_key]
+
+      if current_value.nil?
+        @universal_renderer_props[prop_key] = []
+      elsif !current_value.is_a?(Array)
+        @universal_renderer_props[prop_key] = [current_value]
+      end
+      # At this point, @universal_renderer_props[prop_key] is guaranteed to be an array.
+
+      if value_to_add.is_a?(Array)
+        @universal_renderer_props[prop_key].concat(value_to_add)
+      else
+        @universal_renderer_props[prop_key] << value_to_add
+      end
+    end
+
+    def use_ssr_streaming?
+      %w[1 true yes y].include?(ENV["ENABLE_SSR_STREAMING"]&.downcase)
+    end
+
+    def set_streaming_headers
+      # Tell Cloudflare / proxies not to cache or buffer.
+      response.headers["Cache-Control"] = "no-cache, no-store, must-revalidate"
+      response.headers["Pragma"] = "no-cache"
+      response.headers["Expires"] = "0"
+
+      # Disable Nginx buffering per-response.
+      response.headers["X-Accel-Buffering"] = "no"
+      response.headers["Content-Type"] = "text/html"
+
+      # Remove Content-Length header to prevent buffering.
+      response.headers.delete("Content-Length")
+    end
+
+    def handle_ssr_stream_fallback(response)
+      # SSR streaming failed or was not possible (e.g. server down, config missing).
+      # Ensure response hasn't been touched in a way that prevents a new render.
+      return unless response.committed? || response.body.present?
+
+      Rails.logger.error(
+        "SSR stream fallback:" \
+          "Cannot render default fallback template because response was already committed or body present."
+      )
+      # Close the stream if it's still open to prevent client connection from hanging
+      # when we can't render a fallback page due to already committed response
+      response.stream.close unless response.stream.closed?
+      # If response not committed, no explicit render is called here,
+      # allowing Rails' default rendering behavior to take over.
+    end
+
+    # Overrides the built-in render_to_string.
+    # If you call render_to_string with no explicit template/partial/inline,
+    # it will fall back to 'ssr/index'.
+    def render_to_string(options = {}, *args, &block)
+      if options.is_a?(Hash) && !options.key?(:template) &&
+           !options.key?(:partial) && !options.key?(:inline) &&
+           !options.key?(:json) && !options.key?(:xml)
+        options = options.merge(template: "application/index")
+      end
+      super(options, *args, &block)
+    end
+  end
+end

data/app/helpers/universal_renderer/ssr_helpers.rb

@@ -0,0 +1,19 @@
+module UniversalRenderer
+  module SsrHelpers
+    def ssr_meta
+      "<!-- SSR_META -->".html_safe
+    end
+
+    def ssr_body
+      "<!-- SSR_BODY -->".html_safe
+    end
+
+    def sanitize_ssr(html)
+      sanitize(html, scrubber: SsrScrubber.new)
+    end
+
+    def use_ssr_streaming?
+      %w[1 true yes y].include?(ENV["ENABLE_SSR_STREAMING"]&.downcase)
+    end
+  end
+end

data/app/services/universal_renderer/static_client.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json" # Ensure JSON is required for parsing and generation
+require "uri" # Ensure URI is required for URI parsing
+
+module UniversalRenderer
+  class StaticClient
+    class << self
+      # Performs a POST request to the SSR service to get statically rendered content.
+      #
+      # @param url [String] The URL of the page to render.
+      # @param props [Hash] Additional data to be passed for rendering (renamed from query_data for clarity).
+      # @return [Hash, nil] The parsed JSON response as symbolized keys if successful, otherwise nil.
+      def static(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) # Use uri.request_uri to include path if present in ssr_url
+          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 static request to #{ssr_url} failed: #{response.code} - #{response.message} (URL: #{url})"
+            )
+            nil
+          end
+        rescue Net::OpenTimeout, Net::ReadTimeout => e
+          Rails.logger.error(
+            "SSR static request to #{ssr_url} timed out: #{e.class.name} - #{e.message} (URL: #{url})"
+          )
+          nil
+        rescue StandardError => e
+          Rails.logger.error(
+            "SSR static request to #{ssr_url} failed: #{e.class.name} - #{e.message} (URL: #{url})"
+          )
+          nil
+        end
+      end
+    end
+  end
+end

data/app/services/universal_renderer/stream_client/error_logger.rb

@@ -0,0 +1,29 @@
+module UniversalRenderer
+  class StreamClient
+    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

data/app/services/universal_renderer/stream_client/execution.rb

@@ -0,0 +1,88 @@
+module UniversalRenderer
+  class StreamClient
+    module Execution
+      class << self
+        def _perform_streaming(
+          http_client,
+          http_post_request,
+          response,
+          stream_uri
+        )
+          http_client.request(http_post_request) do |node_res|
+            Execution._handle_node_response_streaming(
+              node_res,
+              response,
+              stream_uri
+            )
+
+            return true
+          end
+          false
+        end
+
+        def _handle_node_response_streaming(node_res, response, stream_uri)
+          if node_res.is_a?(Net::HTTPSuccess)
+            Execution._stream_response_body(node_res, response.stream)
+          else
+            Execution._handle_streaming_for_node_error(
+              node_res,
+              response,
+              stream_uri
+            )
+          end
+        rescue StandardError => e
+          Rails.logger.error(
+            "Error during SSR data transfer or stream writing from #{stream_uri}: #{e.class.name} - #{e.message}"
+          )
+
+          Execution._write_generic_html_error(
+            response.stream,
+            "Streaming Error",
+            "<p>A problem occurred while loading content. Please refresh.</p>"
+          )
+        ensure
+          response.stream.close unless response.stream.closed?
+        end
+
+        def _stream_response_body(source_http_response, target_io_stream)
+          source_http_response.read_body do |chunk|
+            target_io_stream.write(chunk)
+          end
+        end
+
+        def _handle_streaming_for_node_error(node_res, response, stream_uri)
+          Rails.logger.error(
+            "SSR stream server at #{stream_uri} responded with #{node_res.code} #{node_res.message}."
+          )
+
+          is_potentially_viewable_error =
+            node_res["Content-Type"]&.match?(%r{text/html}i)
+
+          if is_potentially_viewable_error
+            Rails.logger.info(
+              "Attempting to stream HTML error page from Node SSR server."
+            )
+            Execution._stream_response_body(node_res, response.stream)
+          else
+            Rails.logger.warn(
+              "Node SSR server error response Content-Type ('#{node_res["Content-Type"]}') is not text/html. " \
+                "Injecting generic error message into the stream."
+            )
+
+            Execution._write_generic_html_error(
+              response.stream,
+              "Application Error",
+              "<p>There was an issue rendering this page. Please try again later.</p>"
+            )
+          end
+        end
+
+        def _write_generic_html_error(stream, title_text, message_html_fragment)
+          return if stream.closed?
+
+          stream.write("<h1>#{title_text}</h1>#{message_html_fragment}")
+        end
+      end
+    end
+  end
+end

data/app/services/universal_renderer/stream_client/setup.rb

@@ -0,0 +1,37 @@
+module UniversalRenderer
+  class StreamClient
+    module Setup
+      class << self
+        def _ensure_ssr_server_url_configured?(config)
+          config.ssr_url.present?
+        end
+
+        def _build_stream_request_components(body, config)
+          # Ensure ssr_url is present, though _ensure_ssr_server_url_configured? should have caught this.
+          # However, direct calls to this method might occur, so a check or reliance on config.ssr_url is important.
+          if config.ssr_url.blank?
+            raise ArgumentError, "SSR URL is not configured."
+          end
+
+          parsed_ssr_url = URI.parse(config.ssr_url)
+          stream_uri = URI.join(parsed_ssr_url, config.ssr_stream_path)
+
+          http = Net::HTTP.new(stream_uri.host, stream_uri.port)
+          http.use_ssl = (stream_uri.scheme == "https")
+          http.open_timeout = config.timeout
+          http.read_timeout = config.timeout
+
+          http_request =
+            Net::HTTP::Post.new(
+              stream_uri.request_uri,
+              "Content-Type" => "application/json"
+            )
+
+          http_request.body = body.to_json
+
+          [stream_uri, http, http_request]
+        end
+      end
+    end
+  end
+end

data/app/services/universal_renderer/stream_client.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "stream_client/setup"
+require_relative "stream_client/execution"
+require_relative "stream_client/error_logger"
+
+module UniversalRenderer
+  class StreamClient
+    extend Setup
+    extend Execution
+    extend ErrorLogger
+
+    # Orchestrates the streaming process for server-side rendering.
+    #
+    # @param url [String] The URL of the page to render.
+    # @param props [Hash] Data to be passed for rendering, including layout HTML.
+    # @param template [String] The HTML template to use for rendering.
+    # @param response [ActionDispatch::Response] The Rails response object to stream to.
+    # @return [Boolean] True if streaming was initiated, false otherwise.
+    def self.stream(url, props, template, response)
+      config = UniversalRenderer.config
+
+      unless Setup._ensure_ssr_server_url_configured?(config)
+        Rails.logger.warn(
+          "StreamClient: SSR URL (config.ssr_url) is not configured. Falling back."
+        )
+        return false
+      end
+
+      stream_uri_obj = nil
+      full_ssr_url_for_log = config.ssr_url.to_s # For logging in case of early error
+
+      begin
+        body = { url: url, props: props, template: template }
+
+        actual_stream_uri, http_client, http_post_request =
+          Setup._build_stream_request_components(body, config)
+
+        stream_uri_obj = actual_stream_uri
+
+        full_ssr_url_for_log = actual_stream_uri.to_s # Update for more specific logging
+      rescue URI::InvalidURIError => e
+        Rails.logger.error(
+          "StreamClient: SSR stream failed due to invalid URI ('#{config.ssr_url}'): #{e.message}"
+        )
+
+        return false
+      rescue StandardError => e
+        _log_setup_error(e, full_ssr_url_for_log)
+
+        return false
+      end
+
+      Execution._perform_streaming(
+        http_client,
+        http_post_request,
+        response,
+        stream_uri_obj
+      )
+    rescue Errno::ECONNREFUSED,
+           Errno::EHOSTUNREACH,
+           Net::OpenTimeout,
+           Net::ReadTimeout,
+           SocketError => e
+      uri_str_for_conn_error =
+        stream_uri_obj ? stream_uri_obj.to_s : full_ssr_url_for_log
+
+      ErrorLogger._log_connection_error(e, uri_str_for_conn_error)
+
+      false
+    rescue StandardError => e
+      uri_str_for_unexpected_error =
+        stream_uri_obj ? stream_uri_obj.to_s : full_ssr_url_for_log
+
+      ErrorLogger._log_unexpected_error(
+        e,
+        uri_str_for_unexpected_error,
+        "StreamClient: Unexpected error during SSR stream process"
+      )
+
+      false
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1 @@
+Rails.application.routes.draw {}

data/lib/generators/universal_renderer/install_generator.rb

@@ -0,0 +1,17 @@
+module UniversalRenderer
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path("templates", __dir__)
+
+    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/generators/universal_renderer/templates/initializer.rb

@@ -0,0 +1,4 @@
+UniversalRenderer.configure do |c|
+  c.ssr_url = ENV.fetch("SSR_SERVER_URL", "http://localhost:3001")
+  c.timeout = 3
+end

data/lib/tasks/universal_renderer_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :universal_renderer do
+#   # Task goes here
+# end

data/lib/universal_renderer/configuration.rb

@@ -0,0 +1,11 @@
+module UniversalRenderer
+  class Configuration
+    attr_accessor :ssr_url, :timeout, :ssr_stream_path
+
+    def initialize
+      @ssr_url = ENV.fetch("SSR_SERVER_URL", nil)
+      @timeout = (ENV["SSR_TIMEOUT"] || 3).to_i
+      @ssr_stream_path = ENV.fetch("SSR_STREAM_PATH", "/stream")
+    end
+  end
+end

data/lib/universal_renderer/engine.rb

@@ -0,0 +1,4 @@
+module UniversalRenderer
+  class Engine < ::Rails::Engine
+  end
+end

data/lib/universal_renderer/ssr_scrubber.rb

@@ -0,0 +1,61 @@
+require "loofah"
+
+module UniversalRenderer
+  class SsrScrubber < ::Loofah::Scrubber
+    def initialize
+      super
+      @direction = :top_down
+    end
+
+    def scrub(node)
+      # Primary actions: stop if script, continue if a passthrough tag, otherwise clean attributes.
+      return Loofah::Scrubber::STOP if handle_script_node(node) # Checks for <script> and removes it
+
+      # Allows <link rel="stylesheet">, <style>, <meta> to pass through this scrubber.
+      return Loofah::Scrubber::CONTINUE if passthrough_node?(node)
+
+      # For all other nodes, clean potentially harmful attributes.
+      clean_attributes(node)
+      # Default Loofah behavior (CONTINUE for children) applies if not returned earlier.
+    end
+
+    private
+
+    # Handles <script> tags: removes them and returns true if a script node was processed.
+    def handle_script_node(node)
+      return false unless node.name == "script"
+
+      node.remove
+      true # Indicates the node was a script and has been handled.
+    end
+
+    # Checks if the node is a type that should bypass detailed attribute scrubbing.
+    def passthrough_node?(node)
+      (node.name == "link" && node["rel"]&.to_s&.downcase == "stylesheet") ||
+        %w[style meta].include?(node.name)
+    end
+
+    # Orchestrates the cleaning of attributes for a given node.
+    def clean_attributes(node)
+      remove_javascript_href(node)
+      remove_event_handlers(node)
+    end
+
+    # Removes "javascript:" hrefs from <a> tags.
+    def remove_javascript_href(node)
+      if node.name == "a" &&
+           node["href"]&.to_s&.downcase&.start_with?("javascript:")
+        node.remove_attribute("href")
+      end
+    end
+
+    # Removes "on*" event handler attributes from any node.
+    def remove_event_handlers(node)
+      attrs_to_remove =
+        node.attributes.keys.select do |name|
+          name.to_s.downcase.start_with?("on")
+        end
+      attrs_to_remove.each { |attr_name| node.remove_attribute(attr_name) }
+    end
+  end
+end

data/lib/universal_renderer/version.rb

@@ -0,0 +1,3 @@
+module UniversalRenderer
+  VERSION = "0.2.4".freeze
+end

data/lib/universal_renderer.rb

@@ -0,0 +1,18 @@
+require "universal_renderer/version"
+require "universal_renderer/engine"
+require "universal_renderer/configuration"
+require "universal_renderer/ssr_scrubber"
+
+module UniversalRenderer
+  class << self
+    attr_writer :config
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield(config)
+    end
+  end
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: universal_renderer
+version: !ruby/object:Gem::Version
+  version: 0.2.4
+platform: ruby
+authors:
+- thaske
+bindir: bin
+cert_chain: []
+date: 2025-05-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: loofah
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.24'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.24'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.5.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 7.1.5.1
+description: Provides helper methods and configuration to forward rendering requests
+  from a Rails app to an external SSR server and return the response.
+email:
+- 10328778+thaske@users.noreply.github.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/controllers/concerns/universal_renderer/rendering.rb
+- app/helpers/universal_renderer/ssr_helpers.rb
+- app/services/universal_renderer/static_client.rb
+- app/services/universal_renderer/stream_client.rb
+- app/services/universal_renderer/stream_client/error_logger.rb
+- app/services/universal_renderer/stream_client/execution.rb
+- app/services/universal_renderer/stream_client/setup.rb
+- config/routes.rb
+- lib/generators/universal_renderer/install_generator.rb
+- lib/generators/universal_renderer/templates/initializer.rb
+- lib/tasks/universal_renderer_tasks.rake
+- lib/universal_renderer.rb
+- lib/universal_renderer/configuration.rb
+- lib/universal_renderer/engine.rb
+- lib/universal_renderer/ssr_scrubber.rb
+- lib/universal_renderer/version.rb
+homepage: https://github.com/thaske/universal_renderer
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/thaske/universal_renderer
+  changelog_uri: https://github.com/thaske/universal_renderer/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Facilitates Server-Side Rendering (SSR) in Rails applications.
+test_files: []