RubyGems - universal_renderer - Versions diffs - 0.4.0 → 0.4.1 - Mend

universal_renderer 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

checksums.yaml +4 -4
data/README.md +58 -67
data/lib/universal_renderer/client/base.rb +48 -47
data/lib/universal_renderer/client/stream/error_logger.rb +18 -20
data/lib/universal_renderer/client/stream/execution.rb +18 -74
data/lib/universal_renderer/client/stream/setup.rb +22 -24
data/lib/universal_renderer/client/stream.rb +7 -9
data/lib/universal_renderer/renderable.rb +7 -8
data/lib/universal_renderer/ssr/helpers.rb +21 -9
data/lib/universal_renderer/ssr/placeholders.rb +1 -1
data/lib/universal_renderer/ssr/response.rb +19 -0
data/lib/universal_renderer/version.rb +1 -1
data/lib/universal_renderer.rb +2 -0
metadata +3 -2

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a84ac507fd401a10c8d36c9b7600d02b4403d84bdcbd63a0c4ac1f707efe0a7f
-  data.tar.gz: deac3f050553555b313864a1eb06ea69ff8e8d25ed78c47a70cb0c54e562012e
+  metadata.gz: 5bc4a2c6514d4a6ae61956f9904ce2387303bbeef0f0f1476a92243405e1489e
+  data.tar.gz: 91fa36be3e8258cf92486ea6631e368e968a8ec67fc7dc5c7732bb9018b92e61
 SHA512:
-  metadata.gz: cda8091a0ad83367e3a0e8bcb93d560ce4b9e778cc543b7edba4084d0e7a540eda82fcd952e40b00115fef62326d15f760de905d882c607224047565d58c9c96
-  data.tar.gz: 15a2798e31d87ca6eec64e0613fedf2da515db85f3b798a792b0917d1719e970862c476c51eaebf65d8550dc0885bd5619edf662819085e3a132d877a4bdf73b
+  metadata.gz: 84c1091722cad8ba00c15e6ac2254a2fde144db10c2cb2440a5fc5a388dc9d13d6b88af595bc4f53166bc76c413d8fec94508d17565072dbac959cd49142a7e0
+  data.tar.gz: 8417a03a6ec8083a70a721f93e945121007721743d2bee8287899e4b76b52be163753ea945875b722930d96c9ccd3eef3b41b0a2e2de9bdcacf1330e644848a7

data/README.md CHANGED Viewed

@@ -16,6 +16,16 @@ UniversalRenderer helps you forward rendering requests to external SSR services,
 - **Automatic fallback** to client-side rendering if SSR fails
 - **View helpers** for easy integration into your layouts
+## Requirements
+> **Heads-up ⚠️** &nbsp;The JavaScript side of UniversalRenderer is **Bun-native**.
+>
+> • You **must** run the SSR server with **Bun ≥ 1.2**.
+>
+> • The exported helpers call Bun's built-in HTTP router and `Response` implementation; they **will not boot under Node, Deno, or Cloudflare Workers**.
+>
+> • The Ruby gem is runtime-agnostic and continues to work on every platform – only the SSR service requires Bun.
 ## Installation
 1. Add to your Gemfile:
@@ -65,8 +75,9 @@ class ProductsController < ApplicationController
     fetch_ssr # or fetch on demand
-    # @ssr will now contain the SSR response, where the symbolized keys
-    # are the same keys returned by the SSR server response.
+    # @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
@@ -80,22 +91,17 @@ end
 ```erb
 <%# "ssr/index" %>
-<%# Now you can use the instance variable @ssr in your layout. %>
-<%# We'll send it with keys :meta, :styles, :root, and :state below. %>
-<%# We can use the provided sanitize_ssr helper to sanitize our content %>
+<%# Inject SSR snippets using the provided helpers. When streaming is enabled
+     these render HTML placeholders (<!-- SSR_HEAD --> / <!-- SSR_BODY -->);
+     otherwise they output the sanitised HTML returned by the SSR service. %>
-<% content_for :meta do %>
-  <%= sanitize_ssr @ssr[:meta] %>
-<% end %>
+<head>
+  <%= ssr_head %>
+</head>
 <div id="root">
-  <%= sanitize_ssr @ssr[:styles] %>
-  <%= sanitize_ssr @ssr[:root] %>
+  <%= ssr_body %>
 </div>
-<script id="state" type="application/json">
-  <%= json_escape(@ssr[:state].to_json) %>
-</script>
 ```
 ## Setting Up the SSR Server
@@ -119,7 +125,7 @@ To set up the SSR server for your Rails application:
      HelmetProvider,
      type HelmetDataContext,
    } from "@dr.pogodin/react-helmet";
-   import { dehydrate, QueryClient, QueryClientProvider } from "react-query";
+   import { QueryClient, QueryClientProvider } from "react-query";
    import { StaticRouter } from "react-router";
    import { ServerStyleSheet } from "styled-components";
@@ -133,7 +139,7 @@ To set up the SSR server for your Rails application:
      const sheet = new ServerStyleSheet();
      const queryClient = new QueryClient();
-     const { query_data } = props;
+     const { query_data = [] } = props;
      query_data.forEach(({ key, data }) => queryClient.setQueryData(key, data));
      const state = dehydrate(queryClient);
@@ -145,29 +151,32 @@ To set up the SSR server for your Rails application:
              <App />
            </StaticRouter>
          </QueryClientProvider>
+         <template id="state" data-state={JSON.stringify(state)} />
        </HelmetProvider>,
      );
-     return { jsx, helmetContext, sheet, state, queryClient };
+     return { jsx, helmetContext, sheet, queryClient };
    }
    ```
-3. Update your `application.tsx` to hydrate the SSR state:
+3. Update your `application.tsx` to hydrate on the client:
    ```tsx
    import { HelmetProvider } from "@dr.pogodin/react-helmet";
-   import { createRoot, hydrateRoot } from "react-dom/client";
-   import { Hydrate, QueryClient, QueryClientProvider } from "react-query";
+   import { hydrateRoot } from "react-dom/client";
    import { BrowserRouter } from "react-router";
+   import { Hydrate, QueryClient, QueryClientProvider } from "react-query";
    import App from "@/App";
    import Metadata from "@/components/Metadata";
    const queryClient = new QueryClient();
-   const stateElement = document.getElementById("state")!;
-   const state = JSON.parse(stateElement.textContent);
-   const app = (
+   const stateEl = document.getElementById("state");
+   const state = JSON.parse(stateEl?.dataset.state ?? "{}");
+   stateEl?.remove();
+   hydrateRoot(
+     document.getElementById("root")!,
      <HelmetProvider>
        <Metadata url={window.location.href} />
        <QueryClientProvider client={queryClient}>
@@ -177,58 +186,40 @@ To set up the SSR server for your Rails application:
            </BrowserRouter>
          </Hydrate>
        </QueryClientProvider>
-     </HelmetProvider>
+     </HelmetProvider>,
    );
-   const rootElement = document.getElementById("root")!;
-   hydrateRoot(rootElement, app);
    ```
 4. Create an SSR entry point at `app/frontend/ssr/ssr.ts`:
    ```ts
+   import { head, transform } from "@/ssr/utils";
    import { renderToString } from "react-dom/server.node";
-   import { createSsrServer } from "universal-renderer";
-   import setup from "@/ssr/setup";
-   import {
-     createRenderStreamTransformer,
-     extractMeta,
-     getRequestLogger,
-     getStateElement,
-   } from "@/ssr/utils";
-   const app = await createSsrServer({
-     middleware: (app) => {
-       app.use(getRequestLogger());
-     },
-     callbacks: {
-       setup: setup,
-       render: async ({ jsx, helmetContext, sheet, state }) => {
-         const root = renderToString(jsx);
-         const meta = extractMeta(helmetContext);
-         const styles = sheet.getStyleTags();
-         return { meta, root, styles, state };
-       },
-       cleanup: async ({ sheet, queryClient }) => {
-         sheet?.seal();
-         queryClient?.clear();
-       },
-       error: (error, _, errorContext) => {
-         console.error(`[SSR] ${errorContext} error:`, error);
-       },
-     },
-     streamCallbacks: {
-       getReactNode: async ({ jsx }) => jsx,
-       getMetaTags: async ({ helmetContext }) => extractMeta(helmetContext),
-       createRenderStreamTransformer,
-       onBeforeWriteClosingHtml: async (res, { state }) => {
-         res.write(getStateElement(state) + "\n");
-       },
-     },
+   import { createServer } from "universal-renderer";
+   import { createServer as createViteServer } from "vite";
+   const vite = await createViteServer({
+     server: { middlewareMode: true },
+     appType: "custom",
    });
-   app.listen(3001, () => {
-     console.log(`[SSR] server started on http://localhost:3001`);
+   await createServer({
+     port: 3001,
+     middleware: vite.middlewares,
+     setup: (await import("@/ssr/setup")).default,
+     render: ({ app, helmet, sheet }) => {
+       const root = renderToString(app);
+       const styles = sheet.getStyleTags();
+       return {
+         head: head({ helmet }),
+         body: `${root}\n${styles}`,
+       };
+     },
+     cleanup: ({ sheet, queryClient }) => {
+       sheet?.seal();
+       queryClient?.clear();
+     },
    });
    ```

data/lib/universal_renderer/client/base.rb CHANGED Viewed

@@ -11,63 +11,64 @@ module UniversalRenderer
     # is needed in its entirety before the Rails view rendering proceeds,
     # as opposed to streaming SSR.
     class Base
-      class << self
-        # Performs a POST request to the SSR service to retrieve the complete SSR content.
-        # This is used for non-streaming SSR, where the entire payload is fetched
-        # before the main application view is rendered.
-        #
-        # @param url [String] The URL of the page to render on the SSR server.
-        #   This should typically be the `request.original_url` from the controller.
-        # @param props [Hash] A hash of props to be passed to the SSR service.
-        #   These props will be available to the frontend components for rendering.
-        # @return [Hash, nil] The parsed JSON response from the SSR service with symbolized keys
-        #   if the request is successful (HTTP 2xx). The structure of the hash depends
-        #   on the SSR service implementation but typically includes keys like `:head`,
-        #   `:body_html`, and `:body_attrs`.
-        #   Returns `nil` if:
-        #   - The `ssr_url` is not configured.
-        #   - The request times out (open or read).
-        #   - The SSR service returns a non-successful HTTP status code.
-        #   - Any other `StandardError` occurs during the request.
-        #   In case of failures, an error message is logged to `Rails.logger`.
-        def fetch(url, props)
-          ssr_url = UniversalRenderer.config.ssr_url
-          return if ssr_url.blank?
+      # Performs a POST request to the SSR service to retrieve the complete SSR content.
+      # This is used for non-streaming SSR, where the entire payload is fetched
+      # before the main application view is rendered.
+      #
+      # @param url [String] The URL of the page to render on the SSR server.
+      #   This should typically be the `request.original_url` from the controller.
+      # @param props [Hash] A hash of props to be passed to the SSR service.
+      #   These props will be available to the frontend components for rendering.
+      # @return [UniversalRenderer::SSR::Response, nil] The SSR payload wrapped in
+      #   a {UniversalRenderer::SSR::Response} struct when the request is successful
+      #   (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
+        return if ssr_url.blank?
-          timeout = UniversalRenderer.config.timeout
+        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
+        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"
+          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 = http.request(request)
-            if response.is_a?(Net::HTTPSuccess)
-              JSON.parse(response.body).deep_symbolize_keys
-            else
-              Rails.logger.error(
-                "SSR fetch request to #{ssr_url} failed: #{response.code} - #{response.message} (URL: #{url})"
-              )
-              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})"
+          if response.is_a?(Net::HTTPSuccess)
+            raw_data = JSON.parse(response.body).deep_symbolize_keys
+            # Map the keys we care about to the Struct. The Node service might
+            # send `:body_html` instead of `:body`; favour the latter if
+            # present but fall back gracefully.
+            UniversalRenderer::SSR::Response.new(
+              head: raw_data[:head],
+              body: raw_data[:body] || raw_data[:body_html],
+              body_attrs: raw_data[:body_attrs]
             )
-            nil
-          rescue StandardError => e
+          else
             Rails.logger.error(
-              "SSR fetch request to #{ssr_url} failed: #{e.class.name} - #{e.message} (URL: #{url})"
+              "SSR fetch request to #{ssr_url} failed: #{response.code} - #{response.message} (URL: #{url})"
             )
             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})"
+          )
+          nil
+        rescue StandardError => e
+          Rails.logger.error(
+            "SSR fetch request to #{ssr_url} failed: #{e.class.name} - #{e.message} (URL: #{url})"
+          )
+          nil
         end
       end
     end

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

@@ -2,28 +2,26 @@ module UniversalRenderer
   module Client
     class Stream
       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 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}"
+          )
+        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 self.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
+        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}"
+          )
         end
       end
     end

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

@@ -2,91 +2,35 @@ 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)
+        def self.perform_streaming(
+          http_client,
+          http_post_request,
+          response,
+          stream_uri
+        )
+          http_client.request(http_post_request) do |node_res|
             if node_res.is_a?(Net::HTTPSuccess)
-              Execution._stream_response_body(node_res, response.stream)
+              node_res.read_body { |chunk| response.stream.write(chunk) }
             else
-              Execution._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}."
               )
+              # Close stream without forwarding error to allow fallback to client rendering
+              response.stream.close unless response.stream.closed?
+              false
             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>",
+              "Error during SSR data transfer or stream writing from #{stream_uri}: #{e.class.name} - #{e.message}"
             )
+            false
           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
+          true
         end
       end
     end

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

@@ -2,36 +2,34 @@ module UniversalRenderer
   module Client
     class Stream
       module Setup
-        class << self
-          def _ensure_ssr_server_url_configured?(config)
-            config.ssr_url.present?
-          end
+        def self.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
+        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
-            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.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 = 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 =
+            Net::HTTP::Post.new(
+              stream_uri.request_uri,
+              "Content-Type" => "application/json"
+            )
-            http_request.body = body.to_json
+          http_request.body = body.to_json
-            [stream_uri, http, http_request]
-          end
+          [stream_uri, http, http_request]
         end
       end
     end

data/lib/universal_renderer/client/stream.rb CHANGED Viewed

@@ -18,10 +18,10 @@ module UniversalRenderer
       # @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)
+      def self.call(url, props, template, response)
         config = UniversalRenderer.config
-        unless Setup._ensure_ssr_server_url_configured?(config)
+        unless Setup.ensure_ssr_server_url_configured?(config)
           Rails.logger.warn(
             "Stream: SSR URL (config.ssr_url) is not configured. Falling back."
           )
@@ -35,7 +35,7 @@ module UniversalRenderer
           body = { url: url, props: props, template: template }
           actual_stream_uri, http_client, http_post_request =
-            Setup._build_stream_request_components(body, config)
+            Setup.build_stream_request_components(body, config)
           stream_uri_obj = actual_stream_uri
@@ -44,15 +44,13 @@ module UniversalRenderer
           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)
+          log_setup_error(e, full_ssr_url_for_log)
           return false
         end
-        Execution._perform_streaming(
+        Execution.perform_streaming(
           http_client,
           http_post_request,
           response,
@@ -67,14 +65,14 @@ 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)
+        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(
+        ErrorLogger.log_unexpected_error(
           e,
           uri_str_for_unexpected_error,
           "Stream: Unexpected error during SSR stream process"

data/lib/universal_renderer/renderable.rb CHANGED Viewed

@@ -29,22 +29,21 @@ module UniversalRenderer
     #   or `nil` if the fetch fails or SSR is not configured.
     def fetch_ssr
       @ssr =
-        UniversalRenderer::Client::Base.fetch(
+        UniversalRenderer::Client::Base.call(
           request.original_url,
-          @universal_renderer_props,
+          @universal_renderer_props
         )
     end
-    def use_ssr_streaming?
+    def ssr_streaming?
       self.class.try(:ssr_streaming_preference)
     end
     def render(*args, **kwargs)
       return super unless self.class.enable_ssr
       return super unless request.format.html?
-      if use_ssr_streaming?
+      if ssr_streaming?
         success = render_ssr_stream(*args, **kwargs)
         super unless success
       else
@@ -60,11 +59,11 @@ module UniversalRenderer
       current_props = @universal_renderer_props.dup
       streaming_succeeded =
-        UniversalRenderer::Client::Stream.stream(
+        UniversalRenderer::Client::Stream.call(
           request.original_url,
           current_props,
           full_layout,
-          response,
+          response
         )
       # SSR streaming failed or was not possible (e.g. server down, config missing).
@@ -73,7 +72,7 @@ module UniversalRenderer
       else
         Rails.logger.error(
           "SSR stream fallback: " \
-            "Streaming failed, proceeding with standard rendering.",
+            "Streaming failed, proceeding with standard rendering."
         )
         false
       end

data/lib/universal_renderer/ssr/helpers.rb CHANGED Viewed

@@ -1,12 +1,18 @@
 module UniversalRenderer
   module SSR
     module Helpers
-      # @!method ssr_meta
-      #   Outputs a meta tag placeholder for SSR content.
+      # @!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_META -->".
-      def ssr_meta
-        Placeholders::META.html_safe
+      #   @return [String] The HTML-safe string "<!-- SSR_HEAD -->".
+      def ssr_head
+        if ssr_streaming?
+          Placeholders::HEAD.html_safe
+        elsif @ssr && @ssr.head.present?
+          sanitize_ssr(@ssr.head)
+        else
+          ""
+        end
       end
       # @!method ssr_body
@@ -14,7 +20,13 @@ module UniversalRenderer
       #   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
+        if ssr_streaming?
+          Placeholders::BODY.html_safe
+        elsif @ssr && @ssr.body.present?
+          sanitize_ssr(@ssr.body)
+        else
+          ""
+        end
       end
       # @!method sanitize_ssr(html)
@@ -28,7 +40,7 @@ module UniversalRenderer
         sanitize(html, scrubber: Scrubber.new)
       end
-      # @!method use_ssr_streaming?
+      # @!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.
@@ -37,8 +49,8 @@ module UniversalRenderer
       #   - 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?
+      def ssr_streaming?
+        controller.ssr_streaming?
       end
     end
   end

data/lib/universal_renderer/ssr/placeholders.rb CHANGED Viewed

@@ -1,7 +1,7 @@
 module UniversalRenderer
   module SSR
     module Placeholders
-      META = "<!-- SSR_META -->".freeze
+      HEAD = "<!-- SSR_HEAD -->".freeze
       BODY = "<!-- SSR_BODY -->".freeze
     end
   end

data/lib/universal_renderer/ssr/response.rb ADDED Viewed

@@ -0,0 +1,19 @@
+module UniversalRenderer
+  module SSR
+    # Lightweight value object representing the payload returned by the
+    # Node.js SSR service. Using a Struct keeps the data immutable-ish while
+    # still allowing hash-like access (e.g. `response[:head]`).
+    #
+    # The contract between the Ruby Gem and the Node service guarantees that
+    # at minimum the `head` and `body` keys are present. Additional keys are
+    # accepted but ignored (see {UniversalRenderer::Client::Base}).
+    #
+    # @!attribute head
+    #   @return [String, nil] Raw <head> HTML snippet produced by the renderer.
+    # @!attribute body
+    #   @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)
+  end
+end

data/lib/universal_renderer/version.rb CHANGED Viewed

@@ -1,3 +1,3 @@
 module UniversalRenderer
-  VERSION = "0.4.0".freeze
+  VERSION = "0.4.1".freeze
 end

data/lib/universal_renderer.rb CHANGED Viewed

@@ -4,6 +4,8 @@ require "universal_renderer/configuration"
 require "universal_renderer/renderable"
+require "universal_renderer/ssr/response"
 require "universal_renderer/client/base"
 require "universal_renderer/client/stream"

metadata CHANGED Viewed

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: universal_renderer
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
 platform: ruby
 authors:
 - thaske
 bindir: bin
 cert_chain: []
-date: 2025-05-21 00:00:00.000000000 Z
+date: 2025-05-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: loofah
@@ -63,6 +63,7 @@ files:
 - lib/universal_renderer/renderable.rb
 - lib/universal_renderer/ssr/helpers.rb
 - lib/universal_renderer/ssr/placeholders.rb
+- lib/universal_renderer/ssr/response.rb
 - lib/universal_renderer/ssr/scrubber.rb
 - lib/universal_renderer/version.rb
 homepage: https://github.com/thaske/universal_renderer