universal_renderer 0.2.4 → 0.3.1

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

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

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,87 @@
+# 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,
+             IOError => 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::Renderable
+    end
   end
 end

data/lib/universal_renderer/renderable.rb

@@ -0,0 +1,162 @@
+module UniversalRenderer
+  module Renderable
+    extend ActiveSupport::Concern
+
+    included do
+      include ActionController::Live
+      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 render(*args, **kwargs)
+      return super unless self.class.enable_ssr
+
+      return super unless request.format.html?
+
+      if use_ssr_streaming?
+        render_ssr_stream(*args, **kwargs)
+      else
+        fetch_ssr
+        super
+      end
+    end
+
+    def render_ssr_stream(*args, **kwargs)
+      set_streaming_headers
+
+      full_layout = render_to_string(*args, **kwargs)
+
+      split_index = full_layout.index(SSR::Placeholders::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::Client::Stream.stream(
+          request.original_url,
+          current_props,
+          after_meta,
+          response
+        )
+
+      # SSR streaming failed or was not possible (e.g. server down, config missing).
+      unless streaming_succeeded
+        Rails.logger.error(
+          "SSR stream fallback: " \
+            "Streaming failed, proceeding with standard rendering."
+        )
+        response.stream.write(after_meta)
+      end
+
+      response.stream.close unless response.stream.closed?
+    end
+
+    def initialize_props
+      @universal_renderer_props = {}
+    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.
+    #
+    # @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
+        @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 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 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]
+
+      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 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
+  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
+        Placeholders::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
+        Placeholders::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/placeholders.rb

@@ -0,0 +1,8 @@
+module UniversalRenderer
+  module SSR
+    module Placeholders
+      META = "<!-- SSR_META -->".freeze
+      BODY = "<!-- SSR_BODY -->".freeze
+    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.1".freeze
 end

data/lib/universal_renderer.rb

@@ -1,7 +1,15 @@
 require "universal_renderer/version"
 require "universal_renderer/engine"
 require "universal_renderer/configuration"
-require "universal_renderer/ssr_scrubber"
+
+require "universal_renderer/renderable"
+
+require "universal_renderer/client/base"
+require "universal_renderer/client/stream"
+
+require "universal_renderer/ssr/helpers"
+require "universal_renderer/ssr/placeholders"
+require "universal_renderer/ssr/scrubber"
 
 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.1
 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,22 @@ 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/renderable.rb
+- lib/universal_renderer/ssr/helpers.rb
+- lib/universal_renderer/ssr/placeholders.rb
+- lib/universal_renderer/ssr/scrubber.rb
 - lib/universal_renderer/version.rb
 homepage: https://github.com/thaske/universal_renderer
 licenses: