universal_renderer 0.2.4 → 0.3.0

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

@@ -0,0 +1,39 @@
+module UniversalRenderer
+  module Client
+    class Stream
+      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
+end

data/lib/universal_renderer/client/stream.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "stream/error_logger"
+require_relative "stream/execution"
+require_relative "stream/setup"
+
+module UniversalRenderer
+  module Client
+    class Stream
+      extend ErrorLogger
+      extend Execution
+      extend Setup
+
+      # 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(
+            "Stream: 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(
+            "Stream: 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,
+          "Stream: Unexpected error during SSR stream process"
+        )
+
+        false
+      end
+    end
+  end
+end

data/lib/universal_renderer/engine.rb

@@ -1,4 +1,7 @@
 module UniversalRenderer
   class Engine < ::Rails::Engine
+    ActiveSupport.on_load(:action_controller) do
+      include UniversalRenderer::Rendering
+    end
   end
 end

data/{app/controllers/concerns → lib}/universal_renderer/rendering.rb

@@ -4,22 +4,50 @@ module UniversalRenderer
 
     included do
       include ActionController::Live
-      helper UniversalRenderer::SsrHelpers
+      helper UniversalRenderer::SSR::Helpers
       before_action :initialize_props
     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_streaming_preference = 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.
+    #
+    # The SSR content is fetched based on the `request.original_url` and the
+    # `@universal_renderer_props` accumulated for the request.
+    #
+    # @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
+      @ssr =
+        UniversalRenderer::Client::Base.fetch(
+          request.original_url,
+          @universal_renderer_props
+        )
+    end
+
+    def use_ssr_streaming?
+      self.class.try(:ssr_streaming_preference)
+    end
+
     private
 
     def default_render
-      return super unless request.format.html?
+      return super unless self.class.enable_ssr && request.format.html?
+
       if use_ssr_streaming?
         render_ssr_stream
       else
-        @ssr =
-          UniversalRenderer::StaticClient.static(
-            request.original_url,
-            @universal_renderer_props
-          )
+        fetch_ssr
         super
       end
     end
@@ -38,7 +66,7 @@ module UniversalRenderer
       current_props = @universal_renderer_props.dup
 
       streaming_succeeded =
-        UniversalRenderer::StreamClient.stream(
+        UniversalRenderer::Client::Stream.stream(
           request.original_url,
           current_props,
           after_meta,
@@ -52,7 +80,18 @@ module UniversalRenderer
       @universal_renderer_props = {}
     end
 
-    def add_props(key_or_hash, data_value = nil)
+    # Adds a prop or a hash of props to be sent to the SSR service.
+    # Props are deep-stringified if a hash is provided.
+    #
+    # @param key_or_hash [String, Symbol, Hash] The key for the prop or a hash of props.
+    # @param data_value [Object, nil] The value for the prop if `key_or_hash` is a key.
+    #   If `key_or_hash` is a Hash, this parameter is ignored.
+    # @example Adding a single prop
+    #   add_prop(:user_id, 123)
+    # @example Adding multiple props from a hash
+    #   add_prop({theme: "dark", locale: "en"})
+    # @return [void]
+    def add_prop(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
@@ -61,10 +100,22 @@ module UniversalRenderer
     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`),
+    # If the prop does not exist or is `nil`, it\'s initialized as an empty array.
+    # If the prop exists but is not an array (e.g., set as a scalar by `add_prop`),
     # 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.
+    # If `value_to_add` is an array, its elements are concatenated to the existing array.
+    # Otherwise, `value_to_add` is appended as a single element.
+    #
+    # @param key [String, Symbol] The key of the prop to modify.
+    # @param value_to_add [Object, Array] The value or array of values to add to the prop.
+    # @example Pushing a single value
+    #   push_prop(:notifications, "New message")
+    # @example Pushing multiple values from an array
+    #   push_prop(:tags, ["rails", "ruby"])
+    # @example Appending to an existing scalar value (converts to array)
+    #   add_prop(:item, "first")
+    #   push_prop(:item, "second") # @universal_renderer_props becomes { "item" => ["first", "second"] }
+    # @return [void]
     def push_prop(key, value_to_add)
       prop_key = key.to_s
       current_value = @universal_renderer_props[prop_key]
@@ -83,10 +134,6 @@ module UniversalRenderer
       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"
@@ -103,30 +150,19 @@ module UniversalRenderer
 
     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.
+      # 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
+      # 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)
+      # If response not committed, no explicit render is called here,
+      # allowing Rails\' default rendering behavior to take over.
     end
   end
 end

data/lib/universal_renderer/ssr/helpers.rb

@@ -0,0 +1,45 @@
+module UniversalRenderer
+  module SSR
+    module Helpers
+      # @!method ssr_meta
+      #   Outputs a meta tag placeholder for SSR content.
+      #   This placeholder is used by the rendering process to inject SSR metadata.
+      #   @return [String] The HTML-safe string "<!-- SSR_META -->".
+      def ssr_meta
+        "<!-- SSR_META -->".html_safe
+      end
+
+      # @!method ssr_body
+      #   Outputs a body placeholder for SSR content.
+      #   This placeholder is used by the rendering process to inject the main SSR body.
+      #   @return [String] The HTML-safe string "<!-- SSR_BODY -->".
+      def ssr_body
+        "<!-- SSR_BODY -->".html_safe
+      end
+
+      # @!method sanitize_ssr(html)
+      #   Sanitizes HTML content rendered by the SSR service.
+      #   Uses a custom scrubber ({UniversalRenderer::SSR::Scrubber}) to remove potentially
+      #   harmful elements like scripts and event handlers, while allowing safe tags
+      #   like stylesheets and meta tags.
+      #   @param html [String] The HTML string to sanitize.
+      #   @return [String] The sanitized HTML string.
+      def sanitize_ssr(html)
+        sanitize(html, scrubber: Scrubber.new)
+      end
+
+      # @!method use_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
+      #   set on the controller.
+      #   - If `ssr_streaming_preference` is `true`, streaming is enabled.
+      #   - If `ssr_streaming_preference` is `false`, streaming is disabled.
+      #   - If `ssr_streaming_preference` is `nil` (not set), streaming is disabled.
+      #   @return [Boolean, nil] The value of `ssr_streaming_preference` (true, false, or nil).
+      #     In conditional contexts, `nil` will behave as `false`.
+      def use_ssr_streaming?
+        controller.use_ssr_streaming?
+      end
+    end
+  end
+end

data/lib/universal_renderer/ssr/scrubber.rb

@@ -0,0 +1,62 @@
+require "loofah"
+
+module UniversalRenderer
+  module SSR
+    class Scrubber < ::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)
+        return unless node.name == "a" && node["href"]
+        href = node["href"].to_s.downcase
+        node.remove_attribute("href") if href.start_with?("javascript:")
+      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
+end

data/lib/universal_renderer/version.rb

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

data/lib/universal_renderer.rb

@@ -1,7 +1,11 @@
 require "universal_renderer/version"
 require "universal_renderer/engine"
 require "universal_renderer/configuration"
-require "universal_renderer/ssr_scrubber"
+require "universal_renderer/ssr/scrubber"
+require "universal_renderer/client/base"
+require "universal_renderer/client/stream"
+require "universal_renderer/rendering"
+require "universal_renderer/ssr/helpers"
 
 module UniversalRenderer
   class << self

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: universal_renderer
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.3.0
 platform: ruby
 authors:
 - thaske
 bindir: bin
 cert_chain: []
-date: 2025-05-20 00:00:00.000000000 Z
+date: 2025-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: loofah
@@ -30,9 +30,6 @@ dependencies:
     - - "~>"
       - !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
@@ -40,9 +37,6 @@ dependencies:
     - - "~>"
       - !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:
@@ -54,21 +48,21 @@ 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/client/base.rb
+- lib/universal_renderer/client/stream.rb
+- lib/universal_renderer/client/stream/error_logger.rb
+- lib/universal_renderer/client/stream/execution.rb
+- lib/universal_renderer/client/stream/setup.rb
 - lib/universal_renderer/configuration.rb
 - lib/universal_renderer/engine.rb
-- lib/universal_renderer/ssr_scrubber.rb
+- lib/universal_renderer/rendering.rb
+- lib/universal_renderer/ssr/helpers.rb
+- lib/universal_renderer/ssr/scrubber.rb
 - lib/universal_renderer/version.rb
 homepage: https://github.com/thaske/universal_renderer
 licenses:

data/app/helpers/universal_renderer/ssr_helpers.rb

@@ -1,19 +0,0 @@
-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

@@ -1,56 +0,0 @@
-# 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

@@ -1,29 +0,0 @@
-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

@@ -1,88 +0,0 @@
-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