react-email-rails 0.1.0

data/lib/react_email_rails/configuration.rb

@@ -0,0 +1,145 @@
+class ReactEmailRails::Configuration
+  BUNDLE_PATH = "tmp/react-email-rails/emails.js"
+  DEV_RENDER_BIN = "node_modules/.bin/react-email-rails-dev"
+
+  DEFAULT_RENDER_TIMEOUT = 10
+  DEFAULT_RENDER_PROCESS_MAX_REQUESTS = 1_000
+
+  RENDER_MODES = {
+    subprocess: ReactEmailRails::RenderModes::Subprocess,
+    persistent: ReactEmailRails::RenderModes::Persistent,
+  }.freeze
+
+  KEY_TRANSFORMS = {
+    camel: ->(key) { key.to_s.camelize },
+    lower_camel: ->(key) { key.to_s.camelize(:lower) },
+    dash: ->(key) { key.to_s.underscore.dasherize },
+    snake: ->(key) { key.to_s.underscore },
+    none: ->(key) { key },
+  }.freeze
+
+  DEFAULT_RENDER_COMMAND = lambda do
+    if Rails.env.development?
+      [Rails.root.join(DEV_RENDER_BIN).to_s]
+    else
+      ["node", Rails.root.join(BUNDLE_PATH).to_s]
+    end
+  end
+
+  DEFAULT_VERIFY_RENDER_ON_BOOT = false
+
+  attr_accessor(
+    :component_path_resolver,
+    :render_options,
+    :transform_props,
+    :on_render_error,
+    :verify_render_on_boot,
+  )
+  attr_reader(
+    :render_mode,
+    :render_timeout,
+    :render_process_max_requests,
+  )
+
+  class << self
+    def default
+      new.tap do |config|
+        config.component_path_resolver = ->(mailer:, action:) { "#{mailer}/#{action}" }
+        config.render_mode = :subprocess
+        config.render_options = {}
+        config.render_timeout = DEFAULT_RENDER_TIMEOUT
+        config.render_process_max_requests = DEFAULT_RENDER_PROCESS_MAX_REQUESTS
+        config.transform_props = :lower_camel
+        config.on_render_error = nil
+        config.verify_render_on_boot = DEFAULT_VERIFY_RENDER_ON_BOOT
+      end
+    end
+  end
+
+  def verify_render_on_boot?
+    verify_render_on_boot.respond_to?(:call) ? !!verify_render_on_boot.call : !!verify_render_on_boot
+  end
+
+  def render_mode=(value)
+    if (value.is_a?(Symbol) || value.is_a?(String)) && !RENDER_MODES.key?(value.to_sym)
+      raise(ArgumentError, "Unknown react-email-rails render mode: #{value.inspect}")
+    end
+
+    @render_mode = value
+  end
+
+  def render_timeout=(value)
+    raise(ArgumentError, "react-email-rails render_timeout must be positive") unless value.is_a?(Numeric) && value.positive?
+
+    @render_timeout = value
+  end
+
+  def render_process_max_requests=(value)
+    unless value.nil? || (value.is_a?(Integer) && value.positive?)
+      raise(ArgumentError, "react-email-rails render_process_max_requests must be a positive integer or nil")
+    end
+
+    @render_process_max_requests = value
+  end
+
+  def resolved_render_mode
+    return render_mode unless render_mode.is_a?(Symbol) || render_mode.is_a?(String)
+
+    RENDER_MODES.fetch(render_mode.to_sym) do
+      raise(ArgumentError, "Unknown react-email-rails render mode: #{render_mode.inspect}")
+    end
+  end
+
+  def resolve_render_options(context = nil)
+    value =
+      if render_options.respond_to?(:call) && context
+        context.instance_exec(&render_options)
+      elsif render_options.respond_to?(:call)
+        render_options.call
+      else
+        render_options
+      end
+
+    deep_camelize_keys(value.as_json)
+  end
+
+  private
+
+  def resolved_render_command
+    DEFAULT_RENDER_COMMAND.call
+  end
+
+  def serialize_props(props)
+    deep_transform_keys(props.as_json, key_transform)
+  end
+
+  def key_transform
+    transform = transform_props.respond_to?(:to_sym) ? transform_props.to_sym : transform_props
+
+    KEY_TRANSFORMS.fetch(transform) do
+      raise(ArgumentError, "Unknown react-email-rails prop transform: #{transform_props.inspect}")
+    end
+  end
+
+  def deep_transform_keys(value, transform)
+    case value
+    when Array
+      value.map { |item| deep_transform_keys(item, transform) }
+    when Hash
+      value.transform_keys { |key| transform.call(key) }.transform_values { |item| deep_transform_keys(item, transform) }
+    else
+      value
+    end
+  end
+
+  def deep_camelize_keys(value)
+    case value
+    when Array
+      value.map { |item| deep_camelize_keys(item) }
+    when Hash
+      value.transform_keys { |key| key.to_s.camelize(:lower) }.transform_values { |item| deep_camelize_keys(item) }
+    else
+      value
+    end
+  end
+end

data/lib/react_email_rails/props_resolver.rb

@@ -0,0 +1,48 @@
+class ReactEmailRails::PropsResolver
+  INTERNAL_ASSIGN_PREFIX = "_"
+  # Some Action Mailer framework assigns do not use the internal `_` prefix.
+  RESERVED_ASSIGNS = ["params", "rendered_format"].freeze
+
+  def initialize(mailer)
+    @mailer = mailer
+  end
+
+  def resolve(react, props)
+    case react
+    when String
+      [react, props || {}]
+    when Hash
+      raise(ArgumentError, "Parameter `props` is not allowed when passing a Hash to `react`") if props
+
+      [inferred_component, react]
+    when true
+      [inferred_component, assign_props]
+    else
+      raise(ArgumentError, "`react` must be a String, Hash, or true")
+    end
+  end
+
+  private
+
+  attr_reader(:mailer)
+
+  def inferred_component
+    ReactEmailRails.configuration.component_path_resolver.call(
+      mailer: mailer.class.mailer_name,
+      action: mailer.action_name,
+    )
+  end
+
+  def assign_props
+    # `react: true` infers the component name; instance vars become props only when the
+    # mailer opts in. Without it, the component renders with no props.
+    return {} unless mailer.class.react_email_use_instance_props
+
+    mailer.instance_variables.each_with_object({}) do |ivar, props|
+      name = ivar.to_s.delete_prefix("@")
+      next if name.start_with?(INTERNAL_ASSIGN_PREFIX) || RESERVED_ASSIGNS.include?(name)
+
+      props[name] = mailer.instance_variable_get(ivar)
+    end
+  end
+end

data/lib/react_email_rails/railtie.rb

@@ -0,0 +1,16 @@
+class ReactEmailRails::Railtie < Rails::Railtie
+  initializer("react-email-rails.action_mailer") do
+    ActiveSupport.on_load(:action_mailer) do
+      prepend(ReactEmailRails::ActionMailer)
+    end
+  end
+
+  config.after_initialize do
+    if ReactEmailRails.configuration.verify_render_on_boot? && !ReactEmailRails.healthy?
+      Rails.logger.error(
+        "[react-email-rails] render verification failed for command: " \
+          "#{ReactEmailRails.configuration.send(:resolved_render_command).inspect}",
+      )
+    end
+  end
+end

data/lib/react_email_rails/render_error.rb

@@ -0,0 +1 @@
+class ReactEmailRails::RenderError < StandardError; end

data/lib/react_email_rails/render_modes/persistent/command_runner.rb

@@ -0,0 +1,44 @@
+class ReactEmailRails::RenderModes::Persistent::CommandRunner
+  class << self
+    def capture(command, input:, timeout:, max_requests: nil)
+      server_for(command).capture(input:, timeout:, max_requests:)
+    end
+
+    def healthy?(command, timeout:)
+      result = server_for(command).health_check(timeout:)
+      result.status.success? && ReactEmailRails::RenderProtocol.compatible_response?(JSON.parse(result.stdout))
+    rescue StandardError
+      false
+    end
+
+    def stop_all
+      @mutex&.synchronize do
+        @servers&.each_value(&:stop)
+        @servers&.clear
+      end
+    end
+
+    private
+
+    def server_for(command)
+      @mutex ||= Mutex.new
+
+      @mutex.synchronize do
+        reset_after_fork
+        @servers[command.map(&:to_s)] ||= ReactEmailRails::RenderModes::Persistent::Server.new(command)
+      end
+    end
+
+    # A forked child inherits the parent's Server objects and the open pipes to
+    # the parent's render processes. Sharing those pipes interleaves requests
+    # and responses across processes, so drop them (without killing the
+    # parent-owned process) and let this process spawn its own on demand.
+    def reset_after_fork
+      return if @owner_pid == Process.pid && @servers
+
+      @servers&.each_value(&:abandon)
+      @servers = {}
+      @owner_pid = Process.pid
+    end
+  end
+end

data/lib/react_email_rails/render_modes/persistent/server.rb

@@ -0,0 +1,204 @@
+class ReactEmailRails::RenderModes::Persistent::Server
+  STDERR_LIMIT = 8 * 1024
+
+  Status = Data.define(:success) do
+    def success? = success
+  end
+
+  def initialize(command)
+    @command = command
+    @mutex = Mutex.new
+    @stderr_buffer = +""
+    @stderr_mutex = Mutex.new
+    @stdout_buffer = +""
+    @requests = 0
+  end
+
+  def capture(input:, timeout:, max_requests:)
+    @mutex.synchronize do
+      capture_once(input:, timeout:).tap { recycle_if_needed(max_requests) }
+    end
+  rescue Errno::EPIPE, IOError
+    stop
+    begin
+      @mutex.synchronize do
+        capture_once(input:, timeout:).tap { recycle_if_needed(max_requests) }
+      end
+    rescue Errno::EPIPE, IOError
+      failure("render process exited before responding")
+    end
+  end
+
+  def health_check(timeout:)
+    @mutex.synchronize { health_check_once(timeout:) }
+  rescue Errno::EPIPE, IOError
+    stop
+    begin
+      @mutex.synchronize { health_check_once(timeout:) }
+    rescue Errno::EPIPE, IOError
+      failure("render process exited before responding")
+    end
+  end
+
+  def stop
+    if @wait_thread&.alive?
+      terminate_process("TERM", @wait_thread.pid)
+      @wait_thread.join(1)
+      terminate_process("KILL", @wait_thread.pid) if @wait_thread.alive?
+    end
+  rescue Errno::ESRCH, Errno::EPERM
+    nil
+  ensure
+    [@stdin, @stdout, @stderr].compact.each { |io| io.close unless io.closed? }
+    @stderr_reader&.kill
+    @stdin = @stdout = @stderr = @wait_thread = @stderr_reader = nil
+    @stdout_buffer.clear
+  end
+
+  # Release this process's copy of an inherited child's pipes without signalling
+  # the process itself, which is still owned by the parent that started it.
+  def abandon
+    [@stdin, @stdout, @stderr].compact.each { |io| io.close unless io.closed? }
+    @stdin = @stdout = @stderr = @wait_thread = @stderr_reader = nil
+    @stdout_buffer.clear
+  rescue IOError
+    nil
+  end
+
+  private
+
+  attr_reader(:command)
+
+  def capture_once(input:, timeout:)
+    response = request(input, timeout:)
+    return failure(response["error"].to_s.presence || "render process failed") unless response["ok"]
+
+    success(JSON.generate(
+      {
+        protocolVersion: response["protocolVersion"],
+        packageVersion: response["packageVersion"],
+      }.tap do |body|
+        body[:html] = response["html"] if response.key?("html")
+        body[:text] = response["text"] if response.key?("text")
+      end,
+    ))
+  rescue JSON::ParserError => e
+    failure("render process returned invalid JSON: #{e.message}")
+  end
+
+  def health_check_once(timeout:)
+    response = request(JSON.generate(health: true), timeout:)
+    response["ok"] ? success(JSON.generate(response)) : failure(response["error"].to_s.presence || "render process failed")
+  rescue JSON::ParserError => e
+    failure("render process returned invalid JSON: #{e.message}")
+  end
+
+  def start
+    @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(*command, "--persistent", pgroup: true)
+    @stderr_buffer = +""
+    @stdout_buffer = +""
+    @requests = 0
+    @stderr_reader = Thread.new { drain_stderr }
+    @stderr_reader.report_on_exception = false
+  end
+
+  def running?
+    @wait_thread&.alive?
+  end
+
+  def request(input, timeout:)
+    start unless running?
+
+    @stdin.write("#{input}\n")
+    @stdin.flush
+
+    line = read_response_line(timeout)
+    return { "ok" => false, "error" => "render process exited before responding" } unless line
+
+    JSON.parse(line)
+  end
+
+  def read_response_line(timeout)
+    deadline = monotonic_time + timeout
+    line = +""
+
+    loop do
+      if (buffered_line = consume_buffered_response_line)
+        line << buffered_line
+        return line
+      end
+
+      line << @stdout_buffer
+      @stdout_buffer.clear
+
+      remaining = deadline - monotonic_time
+      if remaining <= 0 || IO.select([@stdout], nil, nil, remaining).nil?
+        stop
+        raise(Timeout::Error)
+      end
+
+      begin
+        @stdout_buffer << @stdout.read_nonblock(16 * 1024)
+      rescue IO::WaitReadable
+        next
+      end
+    end
+  rescue EOFError
+    line.presence
+  end
+
+  def consume_buffered_response_line
+    separator = @stdout_buffer.index("\n")
+    return unless separator
+
+    @stdout_buffer.slice!(0, separator + 1)
+  end
+
+  def monotonic_time
+    Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+
+  def terminate_process(signal, pid)
+    Process.kill(signal, -pid)
+  rescue Errno::ESRCH, Errno::EPERM
+    nil
+  end
+
+  def drain_stderr
+    @stderr.each do |chunk|
+      @stderr_mutex.synchronize do
+        @stderr_buffer << chunk
+        @stderr_buffer = @stderr_buffer.byteslice(-STDERR_LIMIT, STDERR_LIMIT) if @stderr_buffer.bytesize > STDERR_LIMIT
+      end
+    end
+  rescue IOError
+    nil
+  end
+
+  def success(stdout)
+    ReactEmailRails::RenderModes::Subprocess::CommandRunner::Result.new(
+      stdout:,
+      stderr: "",
+      status: Status.new(true),
+    )
+  end
+
+  def failure(message)
+    ReactEmailRails::RenderModes::Subprocess::CommandRunner::Result.new(
+      stdout: "",
+      stderr: [message, stderr_buffer].reject(&:blank?).join("\n"),
+      status: Status.new(false),
+    )
+  end
+
+  def stderr_buffer
+    @stderr_mutex.synchronize { @stderr_buffer.dup }
+  end
+
+  def recycle_if_needed(max_requests)
+    return unless max_requests&.positive?
+
+    @requests += 1
+    stop if @requests >= max_requests
+  end
+end

data/lib/react_email_rails/render_modes/persistent.rb

@@ -0,0 +1,28 @@
+class ReactEmailRails::RenderModes::Persistent < ReactEmailRails::RenderModes::Subprocess
+  class << self
+    def healthy?(command:, timeout:)
+      CommandRunner.healthy?(command, timeout:)
+    end
+  end
+
+  private
+
+  def capture(input)
+    CommandRunner.capture(
+      command,
+      input:,
+      timeout: render_timeout,
+      max_requests: render_process_max_requests,
+    )
+  rescue Timeout::Error
+    raise(render_error("render process timed out after #{render_timeout}s"))
+  rescue Errno::ENOENT
+    raise(render_error("render command not found: #{command.inspect}"))
+  end
+
+  def render_process_max_requests
+    ReactEmailRails.configuration.send(:render_process_max_requests)
+  end
+end
+
+at_exit { ReactEmailRails::RenderModes::Persistent::CommandRunner.stop_all }

data/lib/react_email_rails/render_modes/subprocess/command_runner.rb

@@ -0,0 +1,56 @@
+class ReactEmailRails::RenderModes::Subprocess::CommandRunner
+  Result = Data.define(:stdout, :stderr, :status)
+
+  class << self
+    def capture(command, input: nil, timeout:)
+      new(command:, input:, timeout:).capture
+    end
+  end
+
+  def initialize(command:, input:, timeout:)
+    @command = command
+    @input = input
+    @timeout = timeout
+  end
+
+  def capture
+    Open3.popen3(*command, pgroup: true) do |stdin, stdout, stderr, wait_thread|
+      out_reader = read_async(stdout)
+      err_reader = read_async(stderr)
+
+      write_input(stdin)
+
+      if wait_thread.join(timeout).nil?
+        terminate_process("KILL", wait_thread.pid)
+        wait_thread.join
+        out_reader.kill
+        err_reader.kill
+        raise(Timeout::Error)
+      end
+
+      Result.new(stdout: out_reader.value, stderr: err_reader.value, status: wait_thread.value)
+    end
+  end
+
+  private
+
+  attr_reader(:command, :input, :timeout)
+
+  def read_async(io)
+    Thread.new { io.read }.tap { |thread| thread.report_on_exception = false }
+  end
+
+  def write_input(stdin)
+    stdin.write(input) if input
+  rescue Errno::EPIPE
+    nil
+  ensure
+    stdin.close
+  end
+
+  def terminate_process(signal, pid)
+    Process.kill(signal, -pid)
+  rescue Errno::ESRCH
+    nil
+  end
+end

data/lib/react_email_rails/render_modes/subprocess.rb

@@ -0,0 +1,99 @@
+class ReactEmailRails::RenderModes::Subprocess
+  class << self
+    def healthy?(command:, timeout:)
+      result = CommandRunner.capture([*command, "--health"], timeout:)
+      result.status.success? && ReactEmailRails::RenderProtocol.compatible_response?(JSON.parse(result.stdout))
+    rescue StandardError
+      false
+    end
+  end
+
+  def initialize(component:, props:, render_options: {})
+    @component = component
+    @props = props
+    @render_options = render_options
+  end
+
+  def render
+    run
+  end
+
+  private
+
+  attr_reader(:component, :props, :render_options)
+
+  def run
+    result = capture(payload_json)
+    raise(render_error(error_message(result.stderr, result.status))) unless result.status.success?
+
+    body = JSON.parse(result.stdout)
+    validate_response!(body)
+    ReactEmailRails::RenderedEmail.new(html: body.fetch("html"), text: body["text"].to_s)
+  rescue JSON::ParserError => e
+    raise(render_error("render process returned invalid JSON: #{e.message}"))
+  rescue KeyError => e
+    raise(render_error("render process returned an invalid response: missing #{e.key.inspect}"))
+  end
+
+  def capture(input)
+    validate_command!
+    CommandRunner.capture(command, input:, timeout: render_timeout)
+  rescue Timeout::Error
+    raise(render_error("render process timed out after #{render_timeout}s"))
+  rescue Errno::ENOENT
+    raise(render_error("render command not found: #{command.inspect}"))
+  end
+
+  def command
+    @command ||= ReactEmailRails.configuration.send(:resolved_render_command)
+  end
+
+  def render_timeout
+    ReactEmailRails.configuration.render_timeout
+  end
+
+  def payload
+    @payload ||= begin
+      payload = {
+        component:,
+        props: ReactEmailRails.configuration.send(:serialize_props, props),
+      }
+      payload[:renderOptions] = render_options if render_options.present?
+      payload
+    end
+  end
+
+  def payload_json
+    @payload_json ||= JSON.generate(payload)
+  end
+
+  def error_message(stderr, status)
+    stderr.to_s.strip.presence || "render process exited with #{status}"
+  end
+
+  def validate_command!
+    command_path = command.first.to_s
+    bundle_path = command[1].to_s
+
+    if command_path.end_with?(ReactEmailRails::Configuration::DEV_RENDER_BIN) && !File.exist?(command_path)
+      raise(render_error("development renderer not found at #{command_path.inspect}; install JavaScript dependencies with npm, pnpm, yarn, or bun"))
+    end
+
+    return unless command_path == "node" && bundle_path.end_with?(ReactEmailRails::Configuration::BUNDLE_PATH)
+    return if File.file?(bundle_path)
+
+    raise(render_error("email bundle not found at #{bundle_path.inspect}; run vite build before rendering React emails"))
+  end
+
+  def validate_response!(body)
+    raise(render_error(ReactEmailRails::RenderProtocol.mismatch_message(body))) unless ReactEmailRails::RenderProtocol.compatible_metadata?(body)
+
+    raise(KeyError.new(key: "html")) unless body.key?("html")
+    raise(render_error("render process returned an invalid response: html must be a string")) unless body["html"].is_a?(String)
+    raise(render_error("render process returned an invalid response: text must be a string")) if body.key?("text") && !body["text"].is_a?(String)
+  end
+
+  def render_error(message)
+    ReactEmailRails::RenderError.new("React Email render failed for #{component}: #{message}")
+  end
+end

data/lib/react_email_rails/render_modes.rb

@@ -0,0 +1 @@
+module ReactEmailRails::RenderModes; end

data/lib/react_email_rails/render_protocol.rb

@@ -0,0 +1,21 @@
+module ReactEmailRails
+  RENDER_PROTOCOL_VERSION = 1
+
+  module RenderProtocol
+    extend(self)
+
+    def compatible_response?(body)
+      body["ok"] == true && compatible_metadata?(body)
+    end
+
+    def compatible_metadata?(body)
+      body["protocolVersion"] == RENDER_PROTOCOL_VERSION &&
+        body["packageVersion"] == VERSION
+    end
+
+    def mismatch_message(body)
+      "renderer version mismatch: expected react-email-rails #{VERSION} protocol #{RENDER_PROTOCOL_VERSION}, " \
+        "got package #{body["packageVersion"].inspect} protocol #{body["protocolVersion"].inspect}"
+    end
+  end
+end

data/lib/react_email_rails/rendered_email.rb

@@ -0,0 +1,3 @@
+module ReactEmailRails
+  RenderedEmail = Data.define(:html, :text)
+end

data/lib/react_email_rails/version.rb

@@ -0,0 +1,3 @@
+module ReactEmailRails
+  VERSION = "0.1.0"
+end