universal_renderer 0.5.2 → 0.7.0

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

@@ -8,7 +8,8 @@ module UniversalRenderer
           http_client,
           http_post_request,
           response,
-          stream_uri
+          stream_uri,
+          &on_failure
         )
           success = false
           chunks_written = false
@@ -28,11 +29,22 @@ module UniversalRenderer
                 end
                 success = true
               else
+                error =
+                  StandardError.new(
+                    "SSR stream server responded with " \
+                      "#{node_res.code} #{node_res.message}"
+                  )
                 UniversalRenderer.log do |log|
                   log.error(
                     "SSR stream server at #{stream_uri} responded with #{node_res.code} #{node_res.message}."
                   )
                 end
+                on_failure&.call(
+                  error,
+                  outcome: :http_error,
+                  status: node_res.code.to_i,
+                  stage: :response
+                )
               end
             end
           rescue StandardError => e
@@ -46,6 +58,11 @@ module UniversalRenderer
             # 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
+            on_failure&.call(
+              e,
+              outcome: failure_outcome(e),
+              stage: :transfer
+            )
             success = chunks_written
           ensure
             response.stream.close if success && !response.stream.closed?
@@ -53,6 +70,15 @@ module UniversalRenderer
 
           success
         end
+
+        def self.failure_outcome(error)
+          return :timeout if error.is_a?(Net::OpenTimeout) ||
+                             error.is_a?(Net::ReadTimeout)
+
+          :error
+        end
+
+        private_class_method :failure_outcome
       end
     end
   end

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

@@ -14,7 +14,12 @@ module UniversalRenderer
           raise ArgumentError, "SSR URL is not configured." if config.url.blank?
 
           parsed_ssr_url = URI.parse(config.url)
-          stream_uri = URI.join(parsed_ssr_url, config.stream_path)
+
+          # URI.join with a relative path replaces the base URL's last path
+          # segment; see Client::Base.absolute_path.
+          stream_path = config.stream_path.to_s
+          stream_path = "/#{stream_path}" unless stream_path.start_with?("/")
+          stream_uri = URI.join(parsed_ssr_url, stream_path)
 
           http = HttpPool.client(stream_uri, config.timeout)
 

data/lib/universal_renderer/client/stream.rb

@@ -7,9 +7,8 @@ require_relative "stream/setup"
 module UniversalRenderer
   module Client
     class Stream
-      extend ErrorLogger
-      extend Execution
-      extend Setup
+      # The three modules below define only singleton methods, so `extend` would
+      # import nothing while reading as though it had. Call sites name the module.
 
       # Orchestrates the streaming process for server-side rendering.
       #
@@ -19,9 +18,20 @@ module UniversalRenderer
       # @param response [ActionDispatch::Response] The Rails response object to stream to.
       # @return [Boolean] True if streaming was initiated, false otherwise.
       def self.call(url, props, template, response)
+        Instrumentation.instrument(url: url, mode: :streaming) do |event|
+          succeeded = perform(url, props, template, response, event)
+          event[:outcome] = :error if !succeeded && event[:outcome] == :ok
+          succeeded
+        end
+      end
+
+      def self.perform(url, props, template, response, event = {})
+        initialize_event(event, url)
+
         config = UniversalRenderer.config
 
         unless Setup.ensure_ssr_server_url_configured?(config)
+          event[:outcome] = :not_configured
           UniversalRenderer.log do |log|
             log.warn(
               "Stream: SSR URL (config.url) is not configured. Falling back."
@@ -43,14 +53,14 @@ module UniversalRenderer
 
           full_ssr_url_for_log = actual_stream_uri.to_s # Update for more specific logging
         rescue URI::InvalidURIError => e
-          UniversalRenderer.log do |log|
-            log.error(
-              "Stream: SSR stream failed due to invalid URI ('#{config.url}'): #{e.message}"
-            )
-          end
+          event[:outcome] = :error
+          event[:error] = e
+          ErrorLogger.log_setup_error(e, config.url.to_s, event)
           return false
         rescue StandardError => e
-          log_setup_error(e, full_ssr_url_for_log)
+          event[:outcome] = :error
+          event[:error] = e
+          ErrorLogger.log_setup_error(e, full_ssr_url_for_log, event)
           return false
         end
 
@@ -59,7 +69,14 @@ module UniversalRenderer
           http_post_request,
           response,
           stream_uri_obj
-        )
+        ) do |error, details|
+          event.merge!(details)
+          event[:error] = error
+          Instrumentation.report(
+            error,
+            event.merge(target: stream_uri_obj.to_s)
+          )
+        end
       rescue Errno::ECONNREFUSED,
              Errno::EHOSTUNREACH,
              Net::OpenTimeout,
@@ -69,21 +86,41 @@ module UniversalRenderer
         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)
+        event[:outcome] = failure_outcome(e)
+        event[:error] = e
+        ErrorLogger.log_connection_error(e, uri_str_for_conn_error, event)
 
         false
       rescue StandardError => e
         uri_str_for_unexpected_error =
           stream_uri_obj ? stream_uri_obj.to_s : full_ssr_url_for_log
 
+        event[:outcome] = :error
+        event[:error] = e
         ErrorLogger.log_unexpected_error(
           e,
           uri_str_for_unexpected_error,
-          "Stream: Unexpected error during SSR stream process"
+          "Stream: Unexpected error during SSR stream process",
+          event
         )
 
         false
       end
+
+      def self.initialize_event(event, url)
+        event[:url] ||= url
+        event[:mode] ||= :streaming
+        event[:outcome] ||= :ok
+      end
+
+      def self.failure_outcome(error)
+        return :timeout if error.is_a?(Net::OpenTimeout) ||
+                           error.is_a?(Net::ReadTimeout)
+
+        :error
+      end
+
+      private_class_method :initialize_event, :failure_outcome
     end
   end
 end

data/lib/universal_renderer/configuration.rb

@@ -3,11 +3,8 @@
 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.
+  # Plain Ruby defaults only. Binding these to ENV is the host application's job,
+  # done in the generated initializer.
   class Configuration
     # HTTP client options.
     class Http
@@ -18,13 +15,66 @@ module UniversalRenderer
       end
     end
 
-    attr_accessor :url, :timeout, :stream_path
+    # Origin of the SSR service, e.g. "http://localhost:3001".
+    attr_accessor :url
+
+    # Open and read timeout, in seconds, for every request to the SSR service.
+    #
+    # Keep this above the renderer's own `renderTimeout` (2.5s by default). A
+    # render that outlives this timeout keeps its concurrency slot until it
+    # finishes, so the renderer must give up first.
+    attr_accessor :timeout
+
+    # Path the blocking renderer is mounted at. Must match the `paths.render`
+    # option given to `createServer`, whose default mounts `/` and `/static`.
+    #
+    # Defaults to nil, meaning the path already in `url`. A relative value is
+    # treated as absolute, since joining it relatively would replace the last
+    # path segment of `url`.
+    attr_accessor :render_path
+
+    # Path the streaming renderer is mounted at on the SSR service. Must match
+    # the `paths.stream` option given to `createServer` in the NPM package.
+    # Normalized the same way as `render_path`.
+    attr_accessor :stream_path
+
+    # Whether `ssr_head`/`ssr_body` run the renderer's HTML through Loofah.
+    #
+    # {SSR::Scrubber} is a blocklist, so this is defense in depth over HTML your
+    # own renderer produced, not a boundary against attacker-controlled markup.
+    # It also parses and rewrites the whole document on every request. On by
+    # default, because the cost is bounded and the mistake it catches is not.
+    attr_accessor :sanitize
+
+    # Scrubber instance used when `sanitize` is true. Defaults to
+    # {UniversalRenderer::SSR::Scrubber}; assign your own Loofah::Scrubber to
+    # widen or narrow what survives.
+    attr_accessor :scrubber
+
+    # Whether the Rails engine includes {UniversalRenderer::Renderable} into
+    # every ActionController::Base descendant. Turn it off and include the
+    # concern only in the controllers that render server-side.
+    attr_accessor :auto_include
+
+    # Optional callable invoked as `call(error, context)` when a configured
+    # render fails, where `context` carries at least `:url` and `:outcome`. A
+    # missing `url` reports `:not_configured` through the notification only.
+    #
+    # Errors are always logged; this exists so they can also reach an exception
+    # tracker, since every failure falls back to client rendering silently.
+    attr_accessor :on_error
+
     attr_reader :http
 
     def initialize
       @url = nil
       @timeout = 3
+      @render_path = nil
       @stream_path = "/stream"
+      @sanitize = true
+      @scrubber = nil
+      @auto_include = true
+      @on_error = nil
       @http = Http.new
     end
   end

data/lib/universal_renderer/engine.rb

@@ -1,7 +1,14 @@
 module UniversalRenderer
   class Engine < ::Rails::Engine
-    ActiveSupport.on_load(:action_controller_base) do
-      include UniversalRenderer::Renderable
+    # After config initializers, so `config.auto_include = false` is honoured
+    # whenever ActionController::Base happens to load.
+    initializer "universal_renderer.renderable",
+                after: :load_config_initializers do
+      ActiveSupport.on_load(:action_controller_base) do
+        if UniversalRenderer.config.auto_include
+          include UniversalRenderer::Renderable
+        end
+      end
     end
   end
 end

data/lib/universal_renderer/instrumentation.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module UniversalRenderer
+  # Every SSR failure falls back to client-side rendering silently, which is
+  # right for availability and useless for operations. These two hooks are the
+  # signal that SSR stopped working.
+  module Instrumentation
+    # ActiveSupport::Notifications event name. Subscribe to record hit rate and
+    # latency:
+    #
+    #   ActiveSupport::Notifications.subscribe("render.universal_renderer") do |event|
+    #     StatsD.timing("ssr.duration", event.duration, tags: ["outcome:#{event.payload[:outcome]}"])
+    #   end
+    #
+    # Payload keys: `:url`, `:mode` (`:blocking` or `:streaming`), `:outcome`
+    # (`:ok`, `:not_configured`, `:http_error`, `:timeout`, or `:error`),
+    # and `:status` / `:error` where applicable.
+    NOTIFICATION = "render.universal_renderer"
+
+    module_function
+
+    # Instruments one render attempt. The block receives the mutable payload so
+    # it can record the outcome it reached.
+    def instrument(url:, mode:)
+      payload = { url: url, mode: mode, outcome: :ok }
+
+      ActiveSupport::Notifications.instrument(NOTIFICATION, payload) do
+        yield payload
+      end
+    end
+
+    # Hands an error to `config.on_error`, if one is configured. A raising
+    # callback must not turn a degraded render into a failed request.
+    def report(error, context)
+      callback = UniversalRenderer.config.on_error
+      return unless callback
+
+      callback.call(error, context)
+    rescue StandardError => e
+      UniversalRenderer.log do |log|
+        log.error(
+          "on_error callback raised: #{e.class.name} - #{e.message}"
+        )
+      end
+    end
+  end
+end