universal_renderer 0.4.3 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 551cd8e80275fa95b8c3f66672f4a4262a25f5f0038fe4c45375b9bc852fbabe
-  data.tar.gz: bad53819a7dfdbdb10fbe1d3317e3877fcb05dc4fc2663ed5954e4975d3bd5b3
+  metadata.gz: f0be3b52440e167e802130a84490b9c7a35f8d0d75ebbed0803f722edeec699b
+  data.tar.gz: 1c9b6213063855a08b0a3cc54771ad99c4679e2ea03f9c9382c181990bdc2db1
 SHA512:
-  metadata.gz: 0eecc4335c6c69929077c77db58fd22e7dbc9db04eeb78efa16826e2b8a35425c270990c96141adf842db4a5d725eacda04f277edbab60f7df41b0580a9b1252
-  data.tar.gz: 4df736ee5b781353f2543f00badc3efbdecd1eebb66a2e6405ff8136599a0f1136ef2fc52dc2d27732cbf7c84bf15a3eb904d3303e7367e1b7c8923fdf0d176c
+  metadata.gz: 45f4c30e25d549e7dd4641179217d7e5b4b0e89819be029cab274aebfd79f3278b48d9392a32b4be719ae81d7bc80a8b8f3edb03dde05b8beb0bd03d3e3338ae
+  data.tar.gz: db4f6173873b402d12c602b6211e0ffe7a46fee8b76fff5fffd7b0fd86e27d05d2dca6792ec208906109e4735a4cbdd0ec779951f4176cd5d0b314b2aa96961d

data/README.md

@@ -33,6 +33,7 @@ UniversalRenderer helps you forward rendering requests to external SSR services,
    ```
 
 3. Run the generator:
+
    ```bash
    $ rails generate universal_renderer:install
    ```
@@ -42,60 +43,31 @@ UniversalRenderer helps you forward rendering requests to external SSR services,
 Configure in `config/initializers/universal_renderer.rb`:
 
 ```ruby
-UniversalRenderer.configure do |config|
-  config.ssr_url = "http://localhost:3001"
+UniversalRenderer.configure do |c|
+  c.url = "http://localhost:3001"
+  c.timeout = 3
+  c.stream_path = "/stream"
+  c.http.pool_size = 5 # persistent Net::HTTP connections per SSR origin
+
+  # Blocking SSR is the default. Enable streaming per controller only when needed:
+  # enable_ssr streaming: true
 end
 ```
 
-## Basic Usage
-
-After installation, you can pass data to your SSR service using `add_prop` in your controllers:
+The gem itself never reads environment variables; it only exposes the plain
+configuration attributes above with sensible defaults. Binding those values to
+`ENV` is entirely up to you, in your own initializer, using whatever keys you
+like. If you want a convention, the suggested env-var prefix is
+`UNIVERSAL_RENDERER_*` (e.g. `UNIVERSAL_RENDERER_URL`):
 
 ```ruby
-class ProductsController < ApplicationController
-  enable_ssr # enables SSR controller-wide
-
-  def show
-    @product = Product.find(params[:id])
-
-    # We can use the provided add_prop method to set a single value.
-    add_prop(:product, @product.as_json)
-
-    # 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 })
-
-    fetch_ssr # or fetch on demand
-
-    # @ssr will now contain a UniversalRenderer::SSR::Response which exposes
-    # `.head`, `.body` and optional `.body_attrs` values returned by the SSR
-    # service.
-  end
-
-  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
+UniversalRenderer.configure do |c|
+  c.url = ENV.fetch("UNIVERSAL_RENDERER_URL", "http://localhost:3001")
+  c.timeout = ENV.fetch("UNIVERSAL_RENDERER_TIMEOUT", 3).to_i
+  # ...
 end
 ```
 
-```erb
-<%# "ssr/index" %>
-
-<%# Inject SSR snippets using the provided helpers %>
-<%# When streaming is enabled these render HTML placeholders %>
-<%# Otherwise they output the sanitised HTML returned by the SSR service %>
-
-<%= content_for :head do %>
-  <%= ssr_head %>
-<% end %>
-
-<div id="root">
-  <%= ssr_body %>
-</div>
-```
-
 ## Setting Up the SSR Server
 
 To set up the SSR server for your Rails application:
@@ -106,8 +78,6 @@ To set up the SSR server for your Rails application:
    $ 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`:
@@ -223,6 +193,28 @@ To set up the SSR server for your Rails application:
    ssr: bin/vite ssr
    ```
 
+## Development
+
+To contribute to this project:
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/thaske/universal_renderer.git
+   cd universal_renderer
+   ```
+
+2. Initialize and update submodules:
+
+   ```bash
+   git submodule update --init --recursive
+   ```
+
+3. Install dependencies:
+   ```bash
+   bundle install
+   ```
+
 ## Contributing
 
 Contributions are welcome! Please follow the coding guidelines in the project documentation.

data/Rakefile

@@ -1,8 +1,11 @@
 require "bundler/setup"
 
 APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
-load "rails/tasks/engine.rake"
-
-load "rails/tasks/statistics.rake"
+if File.exist?(APP_RAKEFILE)
+  load "rails/tasks/engine.rake"
+  load "rails/tasks/statistics.rake"
+end
 
 require "bundler/gem_tasks"
+
+Dir[File.expand_path("lib/tasks/**/*.rake", __dir__)].each { |task| load task }

data/lib/generators/universal_renderer/install_generator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module UniversalRenderer
   class InstallGenerator < Rails::Generators::Base
     source_root File.expand_path("templates", __dir__)
@@ -5,5 +7,13 @@ module UniversalRenderer
     def copy_initializer
       template "initializer.rb", "config/initializers/universal_renderer.rb"
     end
+
+    def show_installation_notes
+      say_status "info", "Universal Renderer installed successfully!"
+      say_status "note", "Next steps:"
+      say_status "",
+                 "  1. Edit config/initializers/universal_renderer.rb to point at your SSR server"
+      say_status "", "  2. Ensure your Node.js/Bun SSR server is running"
+    end
   end
 end

data/lib/generators/universal_renderer/templates/initializer.rb

@@ -1,4 +1,12 @@
+# frozen_string_literal: true
+
 UniversalRenderer.configure do |c|
-  c.ssr_url = ENV.fetch("SSR_SERVER_URL", "http://localhost:3001")
+  # External Node.js/Bun SSR server. Supports streaming via the /stream endpoint.
+  c.url = "http://localhost:3001"
   c.timeout = 3
+  c.stream_path = "/stream"
+  c.http.pool_size = 5
+
+  # Blocking SSR is the default. Enable streaming per controller only when needed:
+  # enable_ssr streaming: true
 end

data/lib/universal_renderer/client/base.rb

@@ -3,6 +3,7 @@
 require "net/http"
 require "json"
 require "uri"
+require_relative "http_pool"
 
 module UniversalRenderer
   module Client
@@ -24,23 +25,18 @@ module UniversalRenderer
       #   (HTTP 2xx). Returns `nil` when the request fails or the SSR service is
       #   unreachable.
       def self.call(url, props)
-        ssr_url = UniversalRenderer.config.ssr_url
+        ssr_url = UniversalRenderer.config.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)
+          response = HttpPool.request(uri, timeout, request)
 
           if response.is_a?(Net::HTTPSuccess)
             raw_data = JSON.parse(response.body).deep_symbolize_keys
@@ -54,20 +50,26 @@ module UniversalRenderer
               body_attrs: raw_data[:body_attrs]
             )
           else
-            Rails.logger.error(
-              "SSR fetch request to #{ssr_url} failed: #{response.code} - #{response.message} (URL: #{url})"
-            )
+            UniversalRenderer.log do |log|
+              log.error(
+                "SSR fetch request to #{ssr_url} failed: #{response.code} - #{response.message} (URL: #{url})"
+              )
+            end
             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})"
-          )
+          UniversalRenderer.log do |log|
+            log.error(
+              "SSR fetch request to #{ssr_url} timed out: #{e.class.name} - #{e.message} (URL: #{url})"
+            )
+          end
           nil
         rescue StandardError => e
-          Rails.logger.error(
-            "SSR fetch request to #{ssr_url} failed: #{e.class.name} - #{e.message} (URL: #{url})"
-          )
+          UniversalRenderer.log do |log|
+            log.error(
+              "SSR fetch request to #{ssr_url} failed: #{e.class.name} - #{e.message} (URL: #{url})"
+            )
+          end
           nil
         end
       end

data/lib/universal_renderer/client/http_pool.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "connection_pool"
+require "net/http"
+
+module UniversalRenderer
+  module Client
+    # Thread-safe pool of persistent Net::HTTP connections keyed by SSR origin.
+    #
+    # Net::HTTP instances are not thread-safe, so each pooled connection is
+    # checked out exclusively. Keeping them started allows Net::HTTP to reuse
+    # the underlying TCP connection for sequential SSR requests.
+    class HttpPool
+      class ClientProxy
+        def initialize(uri, timeout)
+          @uri = uri
+          @timeout = timeout
+        end
+
+        def request(http_request, &block)
+          if block
+            HttpPool.request(@uri, @timeout, http_request) do |response, http|
+              block.call(response, http)
+            end
+          else
+            HttpPool.request(@uri, @timeout, http_request)
+          end
+        end
+      end
+
+      class << self
+        def client(uri, timeout)
+          ClientProxy.new(uri, timeout)
+        end
+
+        def request(uri, timeout, http_request)
+          with_connection(uri, timeout) do |http|
+            if block_given?
+              http.request(http_request) { |response| yield(response, http) }
+            else
+              http.request(http_request)
+            end
+          end
+        end
+
+        def reset!
+          mutex.synchronize do
+            pools.each_value { |pool| pool.shutdown { |http| close(http) } }
+            pools.clear
+          end
+        end
+
+        def close(http)
+          http.finish if http.started?
+        rescue IOError
+          # Already closed by the peer or by another cleanup path.
+        end
+
+        private
+
+        def with_connection(uri, timeout)
+          pool_for(uri, timeout).with do |http|
+            ensure_started(http)
+            yield http
+          rescue StandardError
+            close(http)
+            raise
+          end
+        end
+
+        def pool_for(uri, timeout)
+          key = pool_key(uri, timeout)
+
+          mutex.synchronize do
+            pools[key] ||= ConnectionPool.new(
+              size: pool_size,
+              timeout: timeout
+            ) { build_connection(uri, timeout) }
+          end
+        end
+
+        def build_connection(uri, timeout)
+          Net::HTTP
+            .new(uri.host, uri.port)
+            .tap do |http|
+              http.use_ssl = (uri.scheme == "https")
+              http.open_timeout = timeout
+              http.read_timeout = timeout
+            end
+        end
+
+        def ensure_started(http)
+          http.start unless http.started?
+        end
+
+        def pool_key(uri, timeout)
+          [uri.scheme, uri.host, uri.port, timeout, pool_size].join(":")
+        end
+
+        def pool_size
+          UniversalRenderer.config.http.pool_size
+        end
+
+        def pools
+          @pools ||= {}
+        end
+
+        def mutex
+          @mutex ||= Mutex.new
+        end
+      end
+    end
+  end
+end

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

@@ -4,24 +4,30 @@ module UniversalRenderer
       module ErrorLogger
         def self.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}"
-          )
+          UniversalRenderer.log do |log|
+            log.error(
+              "Unexpected error during SSR stream setup for #{target_uri_string}: " \
+                "#{error.class.name} - #{error.message} at #{backtrace_info}"
+            )
+          end
         end
 
         def self.log_connection_error(error, target_uri_string)
-          Rails.logger.error(
-            "SSR stream connection to #{target_uri_string} failed: #{error.class.name} - #{error.message}"
-          )
+          UniversalRenderer.log do |log|
+            log.error(
+              "SSR stream connection to #{target_uri_string} failed: #{error.class.name} - #{error.message}"
+            )
+          end
         end
 
         def self.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}"
-          )
+          UniversalRenderer.log do |log|
+            log.error(
+              "#{context_message} for #{target_uri_string}: " \
+                "#{error.class.name} - #{error.message} at #{backtrace_info}"
+            )
+          end
         end
       end
     end

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

@@ -1,3 +1,5 @@
+require_relative "../http_pool"
+
 module UniversalRenderer
   module Client
     class Stream
@@ -8,29 +10,48 @@ module UniversalRenderer
           response,
           stream_uri
         )
-          http_client.request(http_post_request) do |node_res|
-            if node_res.is_a?(Net::HTTPSuccess)
-              node_res.read_body { |chunk| response.stream.write(chunk) }
-            else
-              Rails.logger.error(
-                "SSR stream server at #{stream_uri} responded with #{node_res.code} #{node_res.message}."
-              )
+          success = false
+          chunks_written = false
+          upstream_connection = nil
 
-              # Close stream without forwarding error to allow fallback to client rendering
-              response.stream.close unless response.stream.closed?
+          begin
+            http_client.request(http_post_request) do |node_res, connection|
+              upstream_connection = connection
 
-              false
+              if node_res.is_a?(Net::HTTPSuccess)
+                node_res.read_body do |chunk|
+                  # A stream write can fail after handing bytes to the response
+                  # buffer. Mark it first so the caller never falls back onto a
+                  # potentially partial response.
+                  chunks_written = true
+                  response.stream.write(chunk)
+                end
+                success = true
+              else
+                UniversalRenderer.log do |log|
+                  log.error(
+                    "SSR stream server at #{stream_uri} responded with #{node_res.code} #{node_res.message}."
+                  )
+                end
+              end
             end
           rescue StandardError => e
-            Rails.logger.error(
-              "Error during SSR data transfer or stream writing from #{stream_uri}: #{e.class.name} - #{e.message}"
-            )
-            false
+            UniversalRenderer.log do |log|
+              log.error(
+                "Error during SSR data transfer or stream writing from #{stream_uri}: #{e.class.name} - #{e.message}"
+              )
+            end
+
+            # The response may be only partially consumed, so do not reuse the
+            # current persistent connection. Net::HTTP can also raise after its
+            # request block returns while it finalizes that response body.
+            HttpPool.close(upstream_connection) if upstream_connection
+            success = chunks_written
           ensure
-            response.stream.close unless response.stream.closed?
+            response.stream.close if success && !response.stream.closed?
           end
 
-          true
+          success
         end
       end
     end

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

@@ -1,25 +1,22 @@
+require_relative "../http_pool"
+
 module UniversalRenderer
   module Client
     class Stream
       module Setup
         def self.ensure_ssr_server_url_configured?(config)
-          config.ssr_url.present?
+          config.url.present?
         end
 
         def self.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
+          # However, direct calls to this method might occur, so a check or reliance on config.url is important.
+          raise ArgumentError, "SSR URL is not configured." if config.url.blank?
 
-          parsed_ssr_url = URI.parse(config.ssr_url)
-          stream_uri = URI.join(parsed_ssr_url, config.ssr_stream_path)
+          parsed_ssr_url = URI.parse(config.url)
+          stream_uri = URI.join(parsed_ssr_url, config.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 = HttpPool.client(stream_uri, config.timeout)
 
           http_request =
             Net::HTTP::Post.new(

data/lib/universal_renderer/client/stream.rb

@@ -22,14 +22,16 @@ module UniversalRenderer
         config = UniversalRenderer.config
 
         unless Setup.ensure_ssr_server_url_configured?(config)
-          Rails.logger.warn(
-            "Stream: SSR URL (config.ssr_url) is not configured. Falling back."
-          )
+          UniversalRenderer.log do |log|
+            log.warn(
+              "Stream: SSR URL (config.url) is not configured. Falling back."
+            )
+          end
           return false
         end
 
         stream_uri_obj = nil
-        full_ssr_url_for_log = config.ssr_url.to_s # For logging in case of early error
+        full_ssr_url_for_log = config.url.to_s # For logging in case of early error
 
         begin
           body = { url: url, props: props, template: template }
@@ -41,9 +43,11 @@ module UniversalRenderer
 
           full_ssr_url_for_log = actual_stream_uri.to_s # Update for more specific logging
         rescue URI::InvalidURIError => e
-          Rails.logger.error(
-            "Stream: SSR stream failed due to invalid URI ('#{config.ssr_url}'): #{e.message}"
-          )
+          UniversalRenderer.log do |log|
+            log.error(
+              "Stream: SSR stream failed due to invalid URI ('#{config.url}'): #{e.message}"
+            )
+          end
           return false
         rescue StandardError => e
           log_setup_error(e, full_ssr_url_for_log)

data/lib/universal_renderer/configuration.rb

@@ -1,11 +1,31 @@
+# frozen_string_literal: true
+
 module UniversalRenderer
+  # Configuration for UniversalRenderer.
+  #
+  # This object holds plain Ruby defaults only. It never reads environment
+  # variables itself; binding configuration to ENV is the host application's
+  # responsibility, done in the initializer (see the generated
+  # config/initializers/universal_renderer.rb). The documented env-var
+  # convention is the `UNIVERSAL_RENDERER_*` prefix.
   class Configuration
-    attr_accessor :ssr_url, :timeout, :ssr_stream_path
+    # HTTP client options.
+    class Http
+      attr_accessor :pool_size
+
+      def initialize
+        @pool_size = 5
+      end
+    end
+
+    attr_accessor :url, :timeout, :stream_path
+    attr_reader :http
 
     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")
+      @url = nil
+      @timeout = 3
+      @stream_path = "/stream"
+      @http = Http.new
     end
   end
 end

data/lib/universal_renderer/renderable.rb

@@ -3,24 +3,37 @@ module UniversalRenderer
     extend ActiveSupport::Concern
 
     included do
-      include ActionController::Live
       helper UniversalRenderer::SSR::Helpers
-      before_action :initialize_props
+
+      # Distinct from the `enable_ssr` DSL method: reading a class_attribute
+      # named `enable_ssr` on a class that never opted in would invoke the DSL
+      # (arming SSR as a side effect) instead of returning false.
+      class_attribute :ssr_enabled, instance_writer: false, default: false
+      class_attribute :ssr_streaming_preference,
+                      instance_writer: false,
+                      default: nil
+
+      before_action :initialize_props, unless: :skip_universal_renderer?
+    end
+
+    module Streaming
+      extend ActiveSupport::Concern
+
+      included { include ActionController::Live }
     end
 
     class_methods do
       def enable_ssr(options = {})
-        class_attribute :enable_ssr, instance_writer: false
-        self.enable_ssr = true
-
-        class_attribute :ssr_streaming_preference, instance_writer: false
+        self.ssr_enabled = true
         self.ssr_streaming_preference = options[:streaming]
+
+        include UniversalRenderer::Renderable::Streaming if options[:streaming]
       end
     end
 
     # Fetches Server-Side Rendered (SSR) content for the current request.
-    # This method makes a blocking call to the SSR service using {UniversalRenderer::Client::Base.fetch}
-    # and stores the result in the `@ssr` instance variable.
+    # This method makes a blocking call to the SSR service and stores the
+    # result in the `@ssr` instance variable.
     #
     # The SSR content is fetched based on the `request.original_url` and the
     # `@universal_renderer_props` accumulated for the request.
@@ -28,21 +41,24 @@ module UniversalRenderer
     # @return [Hash, nil] The fetched SSR data (typically a hash with keys like `:head`, `:body_html`, `:body_attrs`),
     #   or `nil` if the fetch fails or SSR is not configured.
     def fetch_ssr
+      props = @universal_renderer_props || {}
       @ssr =
         UniversalRenderer::Client::Base.call(
           request.original_url,
-          @universal_renderer_props
+          props
         )
     end
 
     def ssr_streaming?
-      self.class.try(:ssr_streaming_preference)
+      self.class.ssr_streaming_preference
     end
 
     def render(*, **)
-      return super unless self.class.enable_ssr
+      return super unless self.class.ssr_enabled
       return super unless request.format.html?
 
+      # Allow Warden and other authentication mechanisms to complete first
+      # This prevents interference with authentication throws like :warden
       if ssr_streaming?
         success = render_ssr_stream(*, **)
         super unless success
@@ -56,7 +72,7 @@ module UniversalRenderer
 
     def render_ssr_stream(*, **)
       full_layout = render_to_string(*, **)
-      current_props = @universal_renderer_props.dup
+      current_props = (@universal_renderer_props || {}).dup
 
       streaming_succeeded =
         UniversalRenderer::Client::Stream.call(
@@ -66,14 +82,16 @@ module UniversalRenderer
           response
         )
 
-      # SSR streaming failed or was not possible (e.g. server down, config missing).
       if streaming_succeeded
         response.stream.close unless response.stream.closed?
+        true
       else
-        Rails.logger.error(
-          "SSR stream fallback: " \
-            "Streaming failed, proceeding with standard rendering."
-        )
+        UniversalRenderer.log do |log|
+          log.error(
+            "SSR stream fallback: " \
+              "Streaming failed, proceeding with standard rendering."
+          )
+        end
         false
       end
     end
@@ -82,6 +100,22 @@ module UniversalRenderer
       @universal_renderer_props = {}
     end
 
+    # Determines whether to skip universal renderer initialization
+    # This helps prevent interference with authentication flows like Warden
+    def skip_universal_renderer?
+      # Skip if SSR is not enabled for this controller
+      return true unless self.class.ssr_enabled
+
+      # Skip for non-HTML requests
+      return true unless request.format.html?
+
+      # Only skip if we're in the middle of an active Warden throw/catch mechanism
+      # This is more specific and allows SSR for public pages with unauthenticated users
+      return true if defined?(Warden) && request.env["warden"]&.message.present?
+
+      false
+    end
+
     # Adds a prop or a hash of props to be sent to the SSR service.
     # Props are deep-stringified if a hash is provided.
     #
@@ -94,6 +128,7 @@ module UniversalRenderer
     #   add_prop({theme: "dark", locale: "en"})
     # @return [void]
     def add_prop(key_or_hash, data_value = nil)
+      @universal_renderer_props ||= {}
       if data_value.nil? && key_or_hash.is_a?(Hash)
         @universal_renderer_props.merge!(key_or_hash.deep_stringify_keys)
       else
@@ -119,6 +154,7 @@ module UniversalRenderer
     #   push_prop(:item, "second") # @universal_renderer_props becomes { "item" => ["first", "second"] }
     # @return [void]
     def push_prop(key, value_to_add)
+      @universal_renderer_props ||= {}
       prop_key = key.to_s
       current_value = @universal_renderer_props[prop_key]
 
@@ -135,5 +171,18 @@ module UniversalRenderer
         @universal_renderer_props[prop_key] << value_to_add
       end
     end
+
+    # Adds a React Query cache entry that can be hydrated on SSR/client boot.
+    #
+    # @param query_key [Array, String, Symbol] The React Query key.
+    # @param data [Object] The cached query data.
+    # @return [void]
+    def add_query_data(query_key, data)
+      normalized_query_key = query_key.is_a?(Array) ? query_key : [query_key]
+      push_prop(
+        :react_query,
+        { query_key: normalized_query_key, data: data }.deep_stringify_keys
+      )
+    end
   end
 end

data/lib/universal_renderer/ssr/helpers.rb

@@ -40,6 +40,30 @@ module UniversalRenderer
         sanitize(html, scrubber: Scrubber.new)
       end
 
+      # @!method ssr_props_json(props = nil)
+      #   Serializes and JSON-escapes SSR props for safe embedding in HTML attributes.
+      #   Defaults to `@universal_renderer_props` from the current controller/view context.
+      #   @param props [Hash, nil] Optional props hash to serialize.
+      #   @return [String] JSON string escaped for safe HTML embedding.
+      def ssr_props_json(props = nil)
+        raw_props = props || @universal_renderer_props || {}
+        ERB::Util.json_escape(raw_props.to_json)
+      end
+
+      # @!method ssr_props(id: "ssr-props", props: nil)
+      #   Renders a JSON script tag containing SSR props for client hydration.
+      #   @param id [String] DOM id for the script element.
+      #   @param props [Hash, nil] Optional props hash to serialize.
+      #   @return [ActiveSupport::SafeBuffer] Script tag with serialized JSON payload.
+      def ssr_props(id: "ssr-props", props: nil)
+        content_tag(
+          :script,
+          ssr_props_json(props),
+          { id: id, type: "application/json" },
+          false
+        )
+      end
+
       # @!method ssr_streaming?
       #   Determines if SSR streaming should be used for the current request.
       #   The decision is based solely on the `ssr_streaming_preference` class attribute

data/lib/universal_renderer/version.rb

@@ -1,3 +1,3 @@
 module UniversalRenderer
-  VERSION = "0.4.3".freeze
+  VERSION = "0.5.0".freeze
 end

data/lib/universal_renderer.rb

@@ -24,5 +24,39 @@ module UniversalRenderer
     def configure
       yield(config)
     end
+
+    # Configurable logger for the gem. Defaults to the host application's
+    # Rails.logger (when Rails is loaded) wrapped in
+    # ActiveSupport::TaggedLogging so every line is prefixed with
+    # [UniversalRenderer]. Host apps can replace it via
+    # UniversalRenderer.logger = MyLogger.new.
+    def logger
+      @logger || default_logger
+    end
+
+    def logger=(logger)
+      @logger =
+        logger.nil? ? nil : ActiveSupport::TaggedLogging.new(logger)
+    end
+
+    # Tags every block of log output with the gem name so host app logs stay
+    # distinguishable without callers having to remember a prefix. Yields the
+    # tagged logger for convenient use:
+    #   UniversalRenderer.log { |log| log.error("...") }
+    def log
+      logger.tagged("UniversalRenderer") { yield logger }
+    end
+
+    private
+
+    def default_logger
+      base =
+        if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+          Rails.logger
+        else
+          ActiveSupport::Logger.new($stdout)
+        end
+      ActiveSupport::TaggedLogging.new(base)
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: universal_renderer
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.5.0
 platform: ruby
 authors:
 - thaske
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: connection_pool
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
 - !ruby/object:Gem::Dependency
   name: loofah
   requirement: !ruby/object:Gem::Requirement
@@ -59,6 +73,7 @@ files:
 - lib/tasks/universal_renderer_tasks.rake
 - lib/universal_renderer.rb
 - lib/universal_renderer/client/base.rb
+- lib/universal_renderer/client/http_pool.rb
 - lib/universal_renderer/client/stream.rb
 - lib/universal_renderer/client/stream/error_logger.rb
 - lib/universal_renderer/client/stream/execution.rb
@@ -93,7 +108,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.8
 specification_version: 4
 summary: Facilitates Server-Side Rendering (SSR) in Rails applications.
 test_files: []