universal_renderer 0.5.2 → 0.7.0

data/lib/universal_renderer/renderable.rb

@@ -1,19 +1,23 @@
 module UniversalRenderer
+  # Controller-side entry point for server-side rendering. Drive it either
+  # declaratively with {ClassMethods#enable_ssr}, or imperatively by calling
+  # {#render_ssr} from the action. A failed or unconfigured render is a no-op:
+  # {#ssr?} returns false and the layout falls back to client-side rendering.
   module Renderable
     extend ActiveSupport::Concern
 
     included do
       helper UniversalRenderer::SSR::Helpers
 
-      # 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.
+      # Not named `enable_ssr`: reading a class_attribute by that name would
+      # invoke the DSL method and arm SSR as a side effect.
       class_attribute :ssr_enabled, instance_writer: false, default: false
       class_attribute :ssr_streaming_preference,
                       instance_writer: false,
                       default: nil
+      class_attribute :ssr_conditions, instance_writer: false, default: {}
 
-      before_action :initialize_props, unless: :skip_universal_renderer?
+      helper_method :ssr?, :ssr_response, :ssr_streaming?
     end
 
     module Streaming
@@ -22,98 +26,117 @@ module UniversalRenderer
       included { include ActionController::Live }
     end
 
-    class_methods do
+    module ClassMethods
+      # Arms the automatic render path for this controller.
+      #
+      # @param options [Hash]
+      # @option options [Boolean] :streaming Stream the response instead of
+      #   fetching it in one blocking request. Mixes in ActionController::Live.
+      # @option options [Symbol, Array<Symbol>] :only Restrict to these actions.
+      # @option options [Symbol, Array<Symbol>] :except Skip these actions.
+      # @option options [Symbol, Proc] :if Render only when this evaluates
+      #   truthy. A Symbol names a controller method; a Proc is instance_exec'd
+      #   against the controller.
+      # @option options [Symbol, Proc] :unless Skip when this evaluates truthy.
+      #
+      # @example Public pages only
+      #   enable_ssr only: :show, unless: -> { current_user.present? }
+      # @return [void]
       def enable_ssr(options = {})
         self.ssr_enabled = true
         self.ssr_streaming_preference = options[:streaming]
+        self.ssr_conditions = options.slice(:only, :except, :if, :unless).freeze
 
         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 and stores the
-    # result in the `@ssr` instance variable.
+    # The props accumulated for this request. Mutating the returned hash is
+    # supported, but prefer {#add_prop} / {#push_prop} / {#add_query_data}.
     #
-    # 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
-      props = @universal_renderer_props || {}
-      @ssr =
-        UniversalRenderer::Client::Base.call(
-          request.original_url,
-          props
-        )
+    # @return [Hash]
+    # rubocop:disable Naming/MemoizedInstanceVariableName -- the ivar name is
+    # part of the pre-0.6 surface; layouts and specs in the wild read it.
+    def ssr_props
+      @universal_renderer_props ||= {}
     end
+    # rubocop:enable Naming/MemoizedInstanceVariableName
 
-    def ssr_streaming?
-      self.class.ssr_streaming_preference
-    end
+    # Fetches the SSR payload for the current request and remembers it, so the
+    # view helpers and {#ssr?} can see it. Idempotent.
+    #
+    # @param props [Hash, nil] Props to merge first. Ignored once a render has
+    #   happened, since merging then would change `ssr_props` without affecting
+    #   the response.
+    # @return [UniversalRenderer::SSR::Response, nil] `nil` when SSR is not
+    #   configured or the render failed.
+    def render_ssr(props = nil)
+      return @_ssr_response if defined?(@_ssr_response)
 
-    def render(*, **)
-      return super unless self.class.ssr_enabled
-      return super unless request.format.html?
+      add_prop(props) if props.present?
 
-      # 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
-      else
-        fetch_ssr
-        super
-      end
-    end
+      @_ssr_response =
+        UniversalRenderer::Client::Base.call(request.original_url, ssr_props)
 
-    private
+      @ssr = @_ssr_response # pre-0.6 layouts read this ivar
 
-    def render_ssr_stream(*, **)
-      full_layout = render_to_string(*, **)
-      current_props = (@universal_renderer_props || {}).dup
+      @_ssr_response
+    end
 
-      streaming_succeeded =
-        UniversalRenderer::Client::Stream.call(
-          request.original_url,
-          current_props,
-          full_layout,
-          response
-        )
+    alias fetch_ssr render_ssr
 
-      if streaming_succeeded
-        response.stream.close unless response.stream.closed?
-        true
-      else
-        UniversalRenderer.log do |log|
-          log.error(
-            "SSR stream fallback: " \
-              "Streaming failed, proceeding with standard rendering."
-          )
-        end
-        false
-      end
+    # @return [UniversalRenderer::SSR::Response, nil] The payload from the most
+    #   recent {#render_ssr}, or nil if none succeeded.
+    def ssr_response
+      return @_ssr_response if defined?(@_ssr_response)
+
+      # Tolerate layouts and controllers that assigned @ssr by hand.
+      @ssr
     end
 
-    def initialize_props
-      @universal_renderer_props = {}
+    # Whether this request has server-rendered content to emit. Use it to pick
+    # between a hydration entry point and a client-render entry point.
+    #
+    # True while streaming too, where the HTML arrives after the layout renders.
+    #
+    # @return [Boolean]
+    def ssr?
+      ssr_streaming? || ssr_response.present?
     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
+    # Whether this *request* is being streamed.
+    #
+    # False unless the request would also stream, so the layout never emits the
+    # `<!-- SSR_HEAD -->` / `<!-- SSR_BODY -->` markers into a page no renderer
+    # will see. A failed stream downgrades this for the same reason.
+    #
+    # @return [Boolean]
+    def ssr_streaming?
+      return @_ssr_streaming if defined?(@_ssr_streaming)
+
+      self.class.ssr_streaming_preference.present? && ssr_enabled_for_request?
+    end
 
-      # Skip for non-HTML requests
-      return true unless request.format.html?
+    # Render options that mean "this is not a page". The request format is still
+    # HTML for a `render json:` inside a form post, or for a Turbo Frame, so the
+    # format check alone does not catch them.
+    NON_PAGE_RENDER_OPTIONS = %i[
+      body file inline js json nothing partial plain xml
+    ].freeze
 
-      # 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?
+    def render(*, **options)
+      return super unless ssr_enabled_for_request?
+      return super if options.keys.intersect?(NON_PAGE_RENDER_OPTIONS)
+      # No layout, so nothing calls the helpers that would emit the payload.
+      return super if options[:layout] == false
 
-      false
+      if ssr_streaming?
+        success = render_ssr_stream(*, **options)
+        super unless success
+      else
+        render_ssr
+        super
+      end
     end
 
     # Adds a prop or a hash of props to be sent to the SSR service.
@@ -128,16 +151,15 @@ 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)
+        ssr_props.merge!(key_or_hash.deep_stringify_keys)
       else
-        @universal_renderer_props[key_or_hash.to_s] = data_value
+        ssr_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 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.
@@ -151,38 +173,150 @@ module UniversalRenderer
     #   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"] }
+    #   push_prop(:item, "second") # ssr_props becomes { "item" => ["first", "second"] }
     # @return [void]
     def push_prop(key, value_to_add)
-      @universal_renderer_props ||= {}
+      props = ssr_props
       prop_key = key.to_s
-      current_value = @universal_renderer_props[prop_key]
+      current_value = props[prop_key]
 
       if current_value.nil?
-        @universal_renderer_props[prop_key] = []
+        props[prop_key] = []
       elsif !current_value.is_a?(Array)
-        @universal_renderer_props[prop_key] = [current_value]
+        props[prop_key] = [current_value]
       end
-      # At this point, @universal_renderer_props[prop_key] is guaranteed to be an array.
+      # At this point, 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)
+        props[prop_key].concat(value_to_add)
       else
-        @universal_renderer_props[prop_key] << value_to_add
+        props[prop_key] << value_to_add
       end
     end
 
     # Adds a React Query cache entry that can be hydrated on SSR/client boot.
     #
+    # Entries accumulate under the `react_query` prop as
+    # `{ "query_key" => [...], "data" => ... }`. The NPM package's
+    # `hydrateReactQuery(props, queryClient)` consumes exactly this shape — use
+    # it in `setup` rather than reimplementing the loop.
+    #
     # @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]
+      parts = query_key.is_a?(Array) ? query_key : [query_key]
+
+      # React Query compares keys structurally, so numeric parts have to stay
+      # numeric. `deep_stringify_keys` below only touches hash keys.
+      normalized = parts.map { |part| part.is_a?(Symbol) ? part.to_s : part }
+
       push_prop(
         :react_query,
-        { query_key: normalized_query_key, data: data }.deep_stringify_keys
+        { query_key: normalized, data: data }.deep_stringify_keys
       )
     end
+
+    private
+
+    # Whether the automatic (`enable_ssr`) path should run for this request.
+    # {#render_ssr} deliberately does not consult this: an explicit call is the
+    # caller stating intent.
+    #
+    # Memoized so a caller's `if:` / `unless:` predicate runs once, however many
+    # times the layout asks through `ssr_streaming?`.
+    # rubocop:disable Naming/MemoizedInstanceVariableName -- ivars this concern
+    # sets into a host controller are `_`-prefixed to avoid collisions.
+    def ssr_enabled_for_request?
+      return @_ssr_enabled_for_request if defined?(@_ssr_enabled_for_request)
+
+      @_ssr_enabled_for_request = compute_ssr_enabled_for_request?
+    end
+    # rubocop:enable Naming/MemoizedInstanceVariableName
+
+    def compute_ssr_enabled_for_request?
+      return false unless self.class.ssr_enabled
+      return false unless request.format.html?
+
+      # Only while a Warden throw/catch is in flight, so SSR still runs for
+      # public pages viewed by unauthenticated visitors.
+      return false if defined?(Warden) && request.env["warden"]&.message.present?
+
+      ssr_conditions_met?
+    end
+
+    def ssr_conditions_met?
+      conditions = self.class.ssr_conditions
+      return true if conditions.blank?
+
+      ssr_action_allowed?(conditions) && ssr_guards_pass?(conditions)
+    end
+
+    def ssr_action_allowed?(conditions)
+      action = action_name.to_s
+
+      only = conditions[:only]
+      return false if only && Array(only).map(&:to_s).exclude?(action)
+
+      except = conditions[:except]
+      return false if except && Array(except).map(&:to_s).include?(action)
+
+      true
+    end
+
+    def ssr_guards_pass?(conditions)
+      if_condition = conditions[:if]
+      return false if if_condition && !evaluate_ssr_condition(if_condition)
+
+      unless_condition = conditions[:unless]
+      return false if unless_condition &&
+                      evaluate_ssr_condition(unless_condition)
+
+      true
+    end
+
+    def evaluate_ssr_condition(condition)
+      case condition
+      when Symbol, String
+        send(condition)
+      when Proc
+        condition.arity.zero? ? instance_exec(&condition) : condition.call(self)
+      else
+        raise ArgumentError,
+              "enable_ssr conditions must be a Symbol, String, or Proc, " \
+                "got #{condition.class}"
+      end
+    end
+
+    def render_ssr_stream(*, **)
+      # Rendered while `ssr_streaming?` is still true, so the layout carries the
+      # markers the SSR service splices into.
+      full_layout = render_to_string(*, **)
+
+      streaming_succeeded =
+        UniversalRenderer::Client::Stream.call(
+          request.original_url,
+          ssr_props.dup,
+          full_layout,
+          response
+        )
+
+      if streaming_succeeded
+        response.stream.close unless response.stream.closed?
+        true
+      else
+        # Nothing was written upstream, so the caller re-renders normally.
+        # Downgrade first, or the fallback page ships bare markers and no content.
+        @_ssr_streaming = false
+
+        UniversalRenderer.log do |log|
+          log.error(
+            "SSR stream fallback: " \
+              "Streaming failed, proceeding with standard rendering."
+          )
+        end
+        false
+      end
+    end
   end
 end

data/lib/universal_renderer/ssr/helpers.rb

@@ -1,79 +1,104 @@
 module UniversalRenderer
   module SSR
+    # View helpers for emitting what the SSR service returned. `ssr?`,
+    # `ssr_response`, and `ssr_streaming?` come from the controller via
+    # `helper_method` (see {UniversalRenderer::Renderable}).
     module Helpers
-      # @!method ssr_head
-      #   Outputs a head placeholder for SSR content.
-      #   This placeholder is used by the rendering process to inject SSR metadata.
-      #   @return [String] The HTML-safe string "<!-- SSR_HEAD -->".
+      SAFE_BODY_ATTRIBUTE_NAME = /\A[a-z_:][a-z0-9:._-]*\z/i
+
+      # Server-rendered <head> content, or the streaming placeholder.
+      #
+      # @return [String] Sanitized head HTML, the `<!-- SSR_HEAD -->` marker
+      #   when streaming, or an empty string when there is nothing to emit.
       def ssr_head
-        if ssr_streaming?
-          Placeholders::HEAD
-        elsif @ssr && @ssr.head.present?
-          sanitize_ssr(@ssr.head)
-        else
-          ""
-        end
+        return Placeholders::HEAD if ssr_streaming?
+
+        html = ssr_response&.head
+        html.present? ? sanitize_ssr(html) : ""
       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 -->".
+      # Server-rendered body content, or the streaming placeholder.
+      #
+      # @return [String] Sanitized body HTML, the `<!-- SSR_BODY -->` marker
+      #   when streaming, or an empty string when there is nothing to emit.
       def ssr_body
-        if ssr_streaming?
-          Placeholders::BODY
-        elsif @ssr && @ssr.body.present?
-          sanitize_ssr(@ssr.body)
-        else
-          ""
-        end
-      end
+        return Placeholders::BODY if ssr_streaming?
 
-      # @!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)
+        html = ssr_response&.body
+        html.present? ? sanitize_ssr(html) : ""
       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)
+      # Attributes the renderer asked to be applied to the `<body>` tag:
+      #
+      #   <body class="app" <%= ssr_body_attributes %>>
+      #
+      # A non-Hash is dropped rather than raised on, so a renderer answering 200
+      # with the wrong shape degrades the page instead of breaking the layout.
+      #
+      # @return [ActiveSupport::SafeBuffer] Escaped `name="value"` pairs, or an
+      #   empty buffer when the renderer sent none.
+      def ssr_body_attributes
+        attrs = ssr_response&.body_attrs
+        return "".html_safe unless attrs.is_a?(Hash)
+        return "".html_safe if attrs.empty?
+
+        attrs = sanitize_ssr_body_attributes(attrs) if UniversalRenderer.config.sanitize
+        tag.attributes(attrs)
       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)
+      # Renders the renderer's hydration payload as an inert JSON script tag.
+      #
+      # Return it as `payload` from your `render` callback and read it on the
+      # client with `JSON.parse(el.textContent)`.
+      #
+      # @param id [String] DOM id for the script element.
+      # @return [ActiveSupport::SafeBuffer, nil] The script tag, or nil when the
+      #   renderer sent no payload.
+      def ssr_payload(id: "ssr-payload")
+        payload = ssr_response&.payload
+        return if payload.nil?
+
         content_tag(
           :script,
-          ssr_props_json(props),
+          ERB::Util.json_escape(payload.to_json),
           { 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
-      #   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`.
-      delegate :ssr_streaming?, to: :controller
+      # These back the helpers above; the module is included into the view
+      # context, so a public method here would be callable from any template.
+      private
+
+      # Sanitizes HTML returned by the SSR service, honouring `config.sanitize`
+      # and `config.scrubber`.
+      #
+      # @param html [String] The HTML string to sanitize.
+      # @return [String] The sanitized HTML, or the input marked html_safe when
+      #   sanitization is disabled.
+      def sanitize_ssr(html)
+        config = UniversalRenderer.config
+        # rubocop:disable Rails/OutputSafety -- opting out of sanitization is the
+        # documented meaning of config.sanitize = false.
+        return html.to_s.html_safe unless config.sanitize
+        # rubocop:enable Rails/OutputSafety
+
+        sanitize(html, scrubber: config.scrubber || Scrubber.new)
+      end
+
+      # `tag.attributes` escapes values but does not reject executable names such
+      # as `onload`, so the body-attribute channel needs the same boundary as
+      # `ssr_head` and `ssr_body`.
+      def sanitize_ssr_body_attributes(attrs)
+        attrs.each_with_object({}) do |(name, value), safe|
+          normalized = name.to_s.downcase
+          next unless normalized.match?(SAFE_BODY_ATTRIBUTE_NAME)
+          next if normalized.start_with?("on") || normalized == "srcdoc"
+
+          safe[name] = value
+        end
+      end
+
     end
   end
 end

data/lib/universal_renderer/ssr/response.rb

@@ -14,6 +14,11 @@ module UniversalRenderer
     #   @return [String, nil] Raw body HTML snippet produced by the renderer.
     # @!attribute body_attrs
     #   @return [Hash, nil] A hash of attributes that should be applied to the <body> tag.
-    Response = Struct.new(:head, :body, :body_attrs, keyword_init: true)
+    # @!attribute payload
+    #   @return [Object, nil] Arbitrary JSON-serializable hydration state the
+    #     renderer produced, such as a dehydrated query cache. Emit it with the
+    #     `ssr_payload` helper.
+    Response =
+      Struct.new(:head, :body, :body_attrs, :payload, keyword_init: true)
   end
 end