universal_renderer 0.5.1 → 0.7.0

data/lib/generators/universal_renderer/install_generator.rb

@@ -1,19 +1,77 @@
 # frozen_string_literal: true
 
 module UniversalRenderer
+  # Scaffolds a working SSR setup: the initializer, the two renderer entry points,
+  # the SSR Vite build, the precompile hook, and the web-dyno launcher. Each file
+  # encodes something that is wrong by default and fails silently.
   class InstallGenerator < Rails::Generators::Base
     source_root File.expand_path("templates", __dir__)
 
+    class_option :frontend_dir,
+                 type: :string,
+                 default: "app/frontend",
+                 desc: "Where your JavaScript lives (vite_rails' sourceCodeDir)"
+
+    class_option :skip_frontend,
+                 type: :boolean,
+                 default: false,
+                 desc: "Only write the Ruby-side files"
+
+    class_option :skip_deploy,
+                 type: :boolean,
+                 default: false,
+                 desc: "Skip bin/web and the assets:precompile hook"
+
     def copy_initializer
       template "initializer.rb", "config/initializers/universal_renderer.rb"
     end
 
+    def copy_frontend
+      return if options[:skip_frontend]
+
+      template "ssr/globals.ts", "#{frontend_dir}/ssr/globals.ts"
+      template "ssr/config.ts", "#{frontend_dir}/ssr/config.ts"
+      template "ssr/server.ts", "#{frontend_dir}/ssr/server.ts"
+      template "ssr/dev.ts", "#{frontend_dir}/ssr/dev.ts"
+      template "vite.config.ssr.mts", "vite.config.ssr.mts"
+    end
+
+    def copy_deploy_files
+      return if options[:skip_deploy] || options[:skip_frontend]
+
+      template "ssr.rake", "lib/tasks/ssr.rake"
+      template "web", "bin/web"
+      chmod "bin/web", 0o755
+    end
+
     def show_installation_notes
-      say_status "info", "Universal Renderer installed successfully!"
+      say_status "info", "Universal Renderer installed."
       say_status "note", "Next steps:"
+      if options[:skip_frontend]
+        say_status "", "  1. Review config/initializers/universal_renderer.rb"
+        say_status "", "  2. Connect your existing renderer to that endpoint"
+        say_status "", "  3. Opt a controller in with `enable_ssr` or `render_ssr`"
+        return
+      end
+
+      say_status "", "  1. bun add universal-renderer   (or npm/yarn)"
+      say_status "", "  2. Fill in #{frontend_dir}/ssr/config.ts — the render itself"
+      say_status "", "  3. Add the renderer to Procfile.dev:"
+      say_status "", "       ssr: bun #{frontend_dir}/ssr/dev.ts"
+      say_status "", "  4. Add a build script to package.json:"
       say_status "",
-                 "  1. Edit config/initializers/universal_renderer.rb to point at your SSR server"
-      say_status "", "  2. Ensure your Node.js/Bun SSR server is running"
+                 '       "build:ssr": "vite -c vite.config.ssr.mts build"'
+      say_status "", "  5. Opt a controller in with `enable_ssr` or `render_ssr`"
+      return if options[:skip_deploy]
+
+      say_status "", "  6. Point Procfile's web process at bin/web, which runs"
+      say_status "", "     the renderer alongside your app server"
+    end
+
+    private
+
+    def frontend_dir
+      options[:frontend_dir].delete_suffix("/")
     end
   end
 end

data/lib/generators/universal_renderer/templates/initializer.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
 UniversalRenderer.configure do |c|
-  # External Node.js/Bun SSR server. Supports streaming via the /stream endpoint.
-  c.url = "http://localhost:3001"
+  c.url = ENV.fetch("UNIVERSAL_RENDERER_URL", "http://localhost:3001")
+
+  # Keep this above the renderer's 2.5-second default.
   c.timeout = 3
-  c.stream_path = "/stream"
+
   c.http.pool_size = 5
 
-  # Blocking SSR is the default. Enable streaming per controller only when needed:
-  # enable_ssr streaming: true
+  # c.sanitize = false
+  # c.scrubber = MyScrubber.new
+  # c.auto_include = false
+  # c.on_error = ->(error, context) { Sentry.capture_exception(error, extra: context) }
 end

data/lib/generators/universal_renderer/templates/ssr/config.ts

@@ -0,0 +1,40 @@
+// The render lifecycle: setup may await; prepare mutates shared state immediately
+// before rendering; cleanup restores it. With concurrency: 1, prepare through
+// cleanup never overlap.
+
+import { renderToString } from "react-dom/server";
+
+import type { SsrConfig } from "universal-renderer";
+
+import { setBrowserLocation } from "./globals";
+
+export default {
+  setup: async (url, props) => {
+    const { pathname, search } = new URL(url);
+    setBrowserLocation(url);
+
+    // hydrateReactQuery(props, queryClient);
+    // await preloadRoute(pathname);
+
+    const location = `${pathname}${search}`;
+    // const app = <StaticRouter location={location}><App /></StaticRouter>;
+
+    return { location, props, app: null as any };
+  },
+
+  prepare: (context) => {
+    // context.previousFlags = { ...FEATURE_FLAGS };
+    // Object.assign(FEATURE_FLAGS, context.props.feature_flags);
+  },
+
+  render: (context) => ({
+    body: renderToString(context.app),
+    // head: context.sheet.getStyleTags(),
+    // payload: { queryCache: dehydrate(queryClient) },
+  }),
+
+  cleanup: (context) => {
+    // Object.assign(FEATURE_FLAGS, context.previousFlags);
+    // context.sheet?.seal();
+  },
+} satisfies SsrConfig<any>;

data/lib/generators/universal_renderer/templates/ssr/dev.ts

@@ -0,0 +1,9 @@
+// Development renderer entry. Loads the render config through a middleware-mode
+// Vite server, so plugins and path aliases apply and edits need no rebuild.
+//
+// Production does not go through this file. See server.ts.
+import "./globals";
+
+const { startDevServer } = await import("universal-renderer/dev");
+
+await startDevServer({ entry: "<%= frontend_dir %>/ssr/config.ts" });

data/lib/generators/universal_renderer/templates/ssr/globals.ts

@@ -0,0 +1,141 @@
+// App-owned browser stubs for SSR. Add only what your graph needs. Defining
+// `window` makes browser-detection checks false process-wide; prefer fixing DOM
+// access in the app where possible.
+
+const noop = () => undefined;
+const g = globalThis as any;
+const MARKER = "__ssrBrowserGlobals";
+
+export const isShimmed = (): boolean => g[MARKER] === true;
+export const SSR_VIEWPORT = { width: 1024, height: 768 };
+
+const makeLocation = (value: string) => {
+  const url = new URL(value);
+  return {
+    href: url.href,
+    protocol: url.protocol,
+    host: url.host,
+    hostname: url.hostname,
+    port: url.port,
+    pathname: url.pathname,
+    search: url.search,
+    hash: url.hash,
+    origin: url.origin,
+    assign: noop,
+    reload: noop,
+    replace: noop,
+    toString: () => url.href,
+  };
+};
+
+const makeStorage = (): Storage =>
+  ({
+    length: 0,
+    clear: noop,
+    getItem: () => null,
+    key: () => null,
+    removeItem: noop,
+    setItem: noop,
+  }) as unknown as Storage;
+
+const makeElement = (): any => ({
+  style: {},
+  dataset: {},
+  children: [],
+  classList: { add: noop, remove: noop, toggle: noop, contains: () => false },
+  setAttribute: noop,
+  removeAttribute: noop,
+  getAttribute: () => null,
+  appendChild: noop,
+  removeChild: noop,
+  addEventListener: noop,
+  removeEventListener: noop,
+  querySelector: () => null,
+  querySelectorAll: () => [],
+  contains: () => false,
+});
+
+export function setBrowserLocation(url: string): void {
+  if (!isShimmed()) return;
+
+  const location = makeLocation(url);
+  g.window.location = location;
+  g.location = location;
+  if (g.document) g.document.URL = location.href;
+}
+
+export function installBrowserGlobals(): boolean {
+  if (isShimmed()) return false;
+  if (typeof g.window !== "undefined" && typeof g.document !== "undefined") {
+    return false;
+  }
+
+  g[MARKER] = true;
+  const location = makeLocation("http://localhost:3000/");
+  const win: any = {
+    location,
+    localStorage: makeStorage(),
+    sessionStorage: makeStorage(),
+    navigator: { userAgent: "ssr", language: "en-US", languages: ["en-US"] },
+    document: {
+      readyState: "complete",
+      title: "",
+      cookie: "",
+      URL: location.href,
+      documentElement: makeElement(),
+      body: makeElement(),
+      head: makeElement(),
+      hidden: false,
+      visibilityState: "visible",
+      createElement: () => makeElement(),
+      getElementById: () => null,
+      querySelector: () => null,
+      querySelectorAll: () => [],
+      addEventListener: noop,
+      removeEventListener: noop,
+    },
+    history: { pushState: noop, replaceState: noop, back: noop, go: noop },
+    matchMedia: (media: string) => ({
+      matches: false,
+      media,
+      addListener: noop,
+      removeListener: noop,
+      addEventListener: noop,
+      removeEventListener: noop,
+    }),
+    getComputedStyle: () => ({ getPropertyValue: () => "" }),
+    requestAnimationFrame: (_cb: () => void) => 0,
+    cancelAnimationFrame: noop,
+    innerWidth: SSR_VIEWPORT.width,
+    innerHeight: SSR_VIEWPORT.height,
+    scrollTo: noop,
+    addEventListener: noop,
+    removeEventListener: noop,
+  };
+
+  win.window = win;
+  win.self = win;
+  win.top = win;
+
+  g.window = win;
+  for (const key of [
+    "document",
+    "navigator",
+    "location",
+    "history",
+    "localStorage",
+    "sessionStorage",
+    "matchMedia",
+    "getComputedStyle",
+    "requestAnimationFrame",
+    "cancelAnimationFrame",
+    "innerWidth",
+    "innerHeight",
+  ]) {
+    if (!(key in g)) g[key] = win[key];
+  }
+
+  return true;
+}
+
+installBrowserGlobals();

data/lib/generators/universal_renderer/templates/ssr/server.ts

@@ -0,0 +1,24 @@
+// Production renderer entry. Renders from the bundle vite.config.ssr.mts builds,
+// with no Vite server and no per-request module transform. Development uses
+// dev.ts instead.
+//
+// Browser globals first. See globals.ts, and delete it if your graph needs none.
+import "./globals";
+
+// Dynamic, not static: static imports all evaluate before the entry body runs, so
+// the import above would land after the app graph has already touched globals.
+//
+// A library that snapshots `typeof window` at module scope must be imported
+// statically *above* `./globals`. Leave a comment saying so, or a formatter
+// re-sorting the imports undoes it.
+const { default: config } = await import("./config");
+const { startServer } = await import("universal-renderer");
+
+await startServer({
+  ...config,
+  // Serialized on purpose. See config.ts.
+  concurrency: 1,
+  // Keep this below the gem's three-second default timeout: a running render
+  // holds its slot, so the renderer must give up before Rails falls back.
+  renderTimeout: 2_500,
+});

data/lib/generators/universal_renderer/templates/ssr.rake

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# No :environment dependency: bundling the frontend does not need Rails booted,
+# and booting it during precompile only adds ways for the build to fail —
+# credentials, a database that is not up yet.
+# rubocop:disable Rails/RakeEnvironment
+namespace :ssr do
+  desc "Build the standalone SSR bundle that bin/web runs (ssr-build/)"
+  task :build do
+    # Goes through the package script rather than invoking `vite` directly:
+    # node_modules/.bin is not on PATH during a deploy build, so a bare `vite`
+    # fails there while working fine in a shell with the toolchain loaded.
+    # Swap `bun run` for `npm run` / `yarn` to match your package manager.
+    sh "bun run build:ssr"
+  end
+end
+# rubocop:enable Rails/RakeEnvironment
+
+# bin/web runs the compiled bundle, so it has to exist by the time a release
+# boots. Build it with the rest of the assets.
+if Rake::Task.task_defined?("assets:precompile")
+  Rake::Task["assets:precompile"].enhance(["ssr:build"])
+else
+  # No asset pipeline here, so define the task rather than skipping the build
+  # and shipping a release with no renderer.
+  Rake::Task.define_task("assets:precompile" => "ssr:build")
+end

data/lib/generators/universal_renderer/templates/vite.config.ssr.mts

@@ -0,0 +1,13 @@
+import react from "@vitejs/plugin-react";
+import { defineSsrConfig } from "universal-renderer/vite";
+
+// Standalone SSR build. defineSsrConfig handles the four settings that are wrong
+// by default for a Rails SSR build; read its docs before overriding them.
+//
+// Note what is absent: vite-plugin-rails, which targets the client manifest
+// pipeline and overrides entrypoints and outDir. Your client build keeps using
+// vite.config.mts, unchanged.
+export default defineSsrConfig({
+  entry: "<%= frontend_dir %>/ssr/server.ts",
+  plugins: [react()],
+});

data/lib/generators/universal_renderer/templates/web

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# Boots the SSR renderer alongside the app server.
+set -uo pipefail
+
+SSR_BUNDLE="${SSR_BUNDLE:-ssr-build/server.mjs}"
+export SSR_PORT="${SSR_PORT:-3001}"
+
+# Override these for non-Bun runtimes or non-Puma app servers.
+SSR_RUNTIME="${SSR_RUNTIME:-bun}"
+WEB_CMD="${WEB_CMD:-bundle exec puma -C config/puma.rb}"
+
+# Set SSR_WATCHDOG=0 to disable health-based renderer restarts.
+SSR_WATCHDOG="${SSR_WATCHDOG:-1}"
+SSR_HEALTH_URL="${SSR_HEALTH_URL:-http://127.0.0.1:${SSR_PORT}/health}"
+SSR_HEALTH_INTERVAL="${SSR_HEALTH_INTERVAL:-10}"
+SSR_HEALTH_FAILURES="${SSR_HEALTH_FAILURES:-3}"
+
+SSR_PID=""
+APP_PID=""
+shutting_down=0
+health_failures=0
+
+start_ssr() {
+  if [ ! -f "$SSR_BUNDLE" ]; then
+    echo "[web] $SSR_BUNDLE missing — serving client-rendered pages only." >&2
+    return
+  fi
+
+  "$SSR_RUNTIME" "$SSR_BUNDLE" &
+  SSR_PID=$!
+  echo "[web] SSR renderer started (pid $SSR_PID, port $SSR_PORT)"
+}
+
+stop_ssr() {
+  [ -n "$SSR_PID" ] || return 0
+
+  kill -TERM "$SSR_PID" 2>/dev/null || true
+  for _ in 1 2 3 4 5; do
+    kill -0 "$SSR_PID" 2>/dev/null || break
+    sleep 1
+  done
+  kill -KILL "$SSR_PID" 2>/dev/null || true
+  wait "$SSR_PID" 2>/dev/null || true
+  SSR_PID=""
+}
+
+check_ssr_health() {
+  [ "$SSR_WATCHDOG" = "1" ] || return 0
+  [ -n "$SSR_PID" ] || return 0
+  command -v curl >/dev/null 2>&1 || return 0
+
+  if curl -fsS --max-time 5 "$SSR_HEALTH_URL" >/dev/null 2>&1; then
+    health_failures=0
+    return 0
+  fi
+
+  health_failures=$((health_failures + 1))
+  [ "$health_failures" -ge "$SSR_HEALTH_FAILURES" ] || return 0
+
+  echo "[web] SSR renderer unhealthy after ${health_failures} checks — restarting." >&2
+  stop_ssr
+  health_failures=0
+  start_ssr
+}
+
+on_signal() {
+  shutting_down=1
+  if [ -n "$APP_PID" ]; then kill -TERM "$APP_PID" 2>/dev/null || true; fi
+}
+trap on_signal INT TERM
+trap 'if [ -n "$SSR_PID" ]; then kill -KILL "$SSR_PID" 2>/dev/null || true; fi' EXIT
+
+start_ssr
+
+# shellcheck disable=SC2086
+$WEB_CMD &
+APP_PID=$!
+
+elapsed=0
+while [ "$shutting_down" -eq 0 ] && kill -0 "$APP_PID" 2>/dev/null; do
+  sleep 1
+  elapsed=$((elapsed + 1))
+  if [ "$shutting_down" -eq 0 ] && [ "$elapsed" -ge "$SSR_HEALTH_INTERVAL" ]; then
+    elapsed=0
+    check_ssr_health
+  fi
+done
+
+wait "$APP_PID"
+APP_STATUS=$?
+APP_PID=""
+
+stop_ssr
+exit "$APP_STATUS"

data/lib/universal_renderer/client/base.rb

@@ -16,6 +16,9 @@ module UniversalRenderer
       # This is used for non-streaming SSR, where the entire payload is fetched
       # before the main application view is rendered.
       #
+      # Emits a `render.universal_renderer` notification for every attempt and
+      # routes failures through `config.on_error`.
+      #
       # @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.
@@ -25,54 +28,106 @@ module UniversalRenderer
       #   (HTTP 2xx). Returns `nil` when the request fails or the SSR service is
       #   unreachable.
       def self.call(url, props)
-        ssr_url = UniversalRenderer.config.url
-        return if ssr_url.blank?
-
-        timeout = UniversalRenderer.config.timeout
-
-        begin
-          uri = URI.parse(ssr_url)
-          request = Net::HTTP::Post.new(uri.request_uri)
-          request.body = { url: url, props: props }.to_json
-          request["Content-Type"] = "application/json"
-
-          response = HttpPool.request(uri, timeout, request)
-
-          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]
-            )
-          else
-            UniversalRenderer.log do |log|
-              log.error(
-                "SSR fetch request to #{ssr_url} failed: #{response.code} - #{response.message} (URL: #{url})"
-              )
-            end
-            nil
-          end
-        rescue Net::OpenTimeout, Net::ReadTimeout => e
-          UniversalRenderer.log do |log|
-            log.error(
-              "SSR fetch request to #{ssr_url} timed out: #{e.class.name} - #{e.message} (URL: #{url})"
-            )
+        config = UniversalRenderer.config
+        ssr_url = config.url
+
+        Instrumentation.instrument(url: url, mode: :blocking) do |event|
+          if ssr_url.blank?
+            event[:outcome] = :not_configured
+            next nil
           end
-          nil
-        rescue StandardError => e
-          UniversalRenderer.log do |log|
-            log.error(
-              "SSR fetch request to #{ssr_url} failed: #{e.class.name} - #{e.message} (URL: #{url})"
-            )
+
+          perform(ssr_url, config, url, props, event)
+        end
+      end
+
+      def self.perform(ssr_url, config, url, props, event)
+        # A nil render_path means the path in `url` is already the endpoint.
+        parsed = URI.parse(ssr_url)
+        uri =
+          if config.render_path.present?
+            URI.join(parsed, absolute_path(config.render_path))
+          else
+            parsed
           end
-          nil
+
+        request = Net::HTTP::Post.new(uri.request_uri)
+        request.body = { url: url, props: props }.to_json
+        request["Content-Type"] = "application/json"
+
+        response = HttpPool.request(uri, config.timeout, request)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          event[:outcome] = :http_error
+          event[:status] = response.code.to_i
+          fail_render(
+            url,
+            uri,
+            event,
+            "responded with #{response.code} #{response.message}"
+          )
+          return nil
+        end
+
+        build_response(JSON.parse(response.body))
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        event[:outcome] = :timeout
+        event[:error] = e
+        fail_render(url, uri, event, "timed out: #{e.class.name} - #{e.message}", e)
+        nil
+      rescue StandardError => e
+        event[:outcome] = :error
+        event[:error] = e
+        fail_render(url, uri, event, "failed: #{e.class.name} - #{e.message}", e)
+        nil
+      end
+
+      # String keys on purpose: `payload` can be a large dehydrated query cache,
+      # and deep-symbolizing it would walk and re-allocate all of it per render.
+      #
+      # The three keys that reach a view helper are type-checked, so a renderer
+      # answering 200 with the wrong shape falls back like any other failed
+      # render instead of raising mid-layout. `perform` rescues the TypeError.
+      def self.build_response(data)
+        unless data.is_a?(Hash)
+          raise TypeError,
+                "SSR service returned #{data.class.name}, expected a JSON object"
+        end
+
+        UniversalRenderer::SSR::Response.new(
+          head: string_or_nil(data["head"]),
+          body: string_or_nil(data["body"]),
+          body_attrs: (data["body_attrs"] if data["body_attrs"].is_a?(Hash)),
+          payload: data["payload"]
+        )
+      end
+
+      def self.string_or_nil(value)
+        value if value.is_a?(String)
+      end
+
+      # URI.join replaces the base URL's last path segment when the joined path is
+      # relative, which would post renders to the wrong endpoint.
+      def self.absolute_path(path)
+        path = path.to_s
+        path.start_with?("/") ? path : "/#{path}"
+      end
+
+      def self.fail_render(url, uri, event, message, error = nil)
+        target = uri ? uri.to_s : UniversalRenderer.config.url.to_s
+
+        UniversalRenderer.log do |log|
+          log.error("SSR fetch request to #{target} #{message} (URL: #{url})")
         end
+
+        Instrumentation.report(
+          error || StandardError.new("SSR fetch request #{message}"),
+          event.merge(target: target)
+        )
       end
+
+      private_class_method :perform, :build_response, :string_or_nil,
+                           :fail_render, :absolute_path
     end
   end
 end

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

@@ -2,7 +2,7 @@ module UniversalRenderer
   module Client
     class Stream
       module ErrorLogger
-        def self.log_setup_error(error, target_uri_string)
+        def self.log_setup_error(error, target_uri_string, context = {})
           backtrace_info = error.backtrace&.first || "No backtrace available"
           UniversalRenderer.log do |log|
             log.error(
@@ -10,17 +10,24 @@ module UniversalRenderer
                 "#{error.class.name} - #{error.message} at #{backtrace_info}"
             )
           end
+          report(error, target_uri_string, :setup, context)
         end
 
-        def self.log_connection_error(error, target_uri_string)
+        def self.log_connection_error(error, target_uri_string, context = {})
           UniversalRenderer.log do |log|
             log.error(
               "SSR stream connection to #{target_uri_string} failed: #{error.class.name} - #{error.message}"
             )
           end
+          report(error, target_uri_string, :connection, context)
         end
 
-        def self.log_unexpected_error(error, target_uri_string, context_message)
+        def self.log_unexpected_error(
+          error,
+          target_uri_string,
+          context_message,
+          context = {}
+        )
           backtrace_info = error.backtrace&.first || "No backtrace available"
           UniversalRenderer.log do |log|
             log.error(
@@ -28,6 +35,21 @@ module UniversalRenderer
                 "#{error.class.name} - #{error.message} at #{backtrace_info}"
             )
           end
+          report(error, target_uri_string, :unexpected, context)
+        end
+
+        # Streaming failures fall back to client-side rendering just as blocking
+        # ones do, so they need the same escape hatch to an exception tracker.
+        def self.report(error, target_uri_string, stage, context = {})
+          Instrumentation.report(
+            error,
+            context.merge(
+              mode: :streaming,
+              outcome: context.fetch(:outcome, :error),
+              stage: stage,
+              target: target_uri_string
+            )
+          )
         end
       end
     end