humid 0.1.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c4f5090d85ea4b1c4998f6c8533816a8875039f2ffe5b5785e3e571092445c6
-  data.tar.gz: 844410054db5d2c89fa3fc1fd3ac4d64f83605cf4a157573ebd6d172b01d0a7f
+  metadata.gz: 1b62f6d6c3c7ffac0ba1c609965742a6a09dafebe0ebb9fc05cbae3c9200299e
+  data.tar.gz: 56557384d6768ada9b8fa9e9403720b5e75f03a579e39483892afcb631cb04a4
 SHA512:
-  metadata.gz: 574e6c64e749180f964a3d9ffe4dd91f18179408901b4b26960b2ef3c9bbe12c601e0879fc97bb60b340ed0270be627aaf0cc92d18827deda5f45dd515d952c4
-  data.tar.gz: b1511fc86f5655ac063bf6d927866bd00096c7ddca23e822e2cd3dbe03a97d1e4f62288f1242c9b436e67695402c2a61a59e4f096a0dc0f3dbf450ac0fbdc250
+  metadata.gz: 4465a746beab25d302782cc71b8a70cd7fe827dc6ce3058e6720056c121bb86357733a9d31a7c266ceee6a53f938b174fec1eef111dbc634aa6699ffccb30ac9
+  data.tar.gz: c5d8a1c61b84b49a14a78c7d198af09871bbdf9cebc8c9bbd1d4b32c2cdd95ac7de2bad06214f80ec12a8507158b8bb95a592eff313e51e454dcd768e5a2cdc1

data/README.md

@@ -2,9 +2,20 @@
 
 ![Build Status](https://github.com/thoughtbot/humid/actions/workflows/build.yml/badge.svg?branch=main)
 
-Humid is a lightweight wrapper around [mini_racer] used to generate Server
-Side Rendered (SSR) pages from your js-bundling builds. While it was built
-for React, it can work with any JS function that returns a HTML string.
+Humid is a set of helper functions for using `mini_racer` for Server Side
+Rendering (SSR). **There are only 2 pure public functions and a `configure` to set
+default args**. `mini_racer` does the heavy lifting, Humid just provides a few
+conveniences.
+
+While it was built with React in mind, it can work with any JS function that
+returns an HTML string.
+
+## Design
+
+Humid is designed for the common case where all data is gathered before
+rendering. Your application fetches everything needed, passes it as props, and
+Humid returns the rendered HTML in a single synchronous call. It does not
+support streaming or async data fetching during render.
 
 ## Caution
 
@@ -26,12 +37,14 @@ For source-map support, also add
 yarn add source-map-support
 ```
 
-
 ## Configuration
 
-Add an initializer to configure
+Add an initializer to configure the default options for `Humid.render`. These
+are overridable on `Humid.render`.
 
 ```ruby
+# app/initializers/humid.rb
+
 Humid.configure do |config|
   # Path to your build file located in `app/assets/builds/`. You should use a
   # separate build apart from your `application.js`.
@@ -55,41 +68,70 @@ Humid.configure do |config|
   # the respective logger levels on the ruby side.
   #
   # Defaults to `nil`
-  config.logger = Rails.env.development? ? Rails.logger : nil
-
-  # Options passed to mini_racer.
-  #
-  # Defaults to empty `{}`.
-  config.context_options = {
-    timeout: 1000,
-    ensure_gc_after_idle: 2000
-  }
+  config.logger = Rails.env.local? ? Rails.logger : nil
 end
 
-# Capybara defines its own puma config which is set up to run a single puma process
-# with a thread pool. This ensures that a context gets created on that process.
-if Rails.env.test?
+# if Rails.env.local?
+#   # Use single_threaded mode for Spring and other forked envs.
+#   MiniRacer::Platform.set_flags! :single_threaded
+#   ctx = MiniRacer::Context.new(timeout: 100, ensure_gc_after_idle: 2000)
+#   MINI_RACER_CONTEXT = Humid.prepare(ctx)
+# end
+```
+
+## Usage
+
+
+### Create the MiniRacer Context.
+
+On local development or test environments, uncomment the below.
+
+```ruby
+if Rails.env.local?
   # Use single_threaded mode for Spring and other forked envs.
   MiniRacer::Platform.set_flags! :single_threaded
-  Humid.create_context
+  ctx = MiniRacer::Context.new(timeout: 100, ensure_gc_after_idle: 2000)
+  MINI_RACER_CONTEXT = Humid.prepare(ctx)
 end
 ```
 
-Then add to your `config/puma.rb`
+On production, keep in mind that `mini_racer` is **thread safe, but not fork
+safe**. When using with web servers that employ forking, create a
+`MINI_RACER_CONTEXT` with options of your choosing **on worker boot. There
+should be no context created on the master process.**
 
-```
-workers ENV.fetch("WEB_CONCURRENCY") { 1 }
+For example with puma:
 
+```ruby
+# config/puma.rb
 on_worker_boot do
-  Humid.create_context
+  ctx = MiniRacer::Context.new(timeout: 100, ensure_gc_after_idle: 2000)
+  MINI_RACER_CONTEXT = Humid.prepare(ctx)
 end
 
 on_worker_shutdown do
-  Humid.dispose
+  MINI_RACER_CONTEXT.dispose
 end
 ```
 
+### Prepare the context with `Humid.prepare`
+
+`Humid.prepare` will prepare the context's environment by [removing
+functions](#functions-not-available), delegate `console.log` and friends to
+your logger, load the SSR js bundle, and add the render function.
+
+You can also override config options per-context:
+
+```ruby
+MINI_RACER_CONTEXT = Humid.prepare(
+  MiniRacer::Context.new(timeout: 1000),
+  application_path: Rails.root.join("other_bundle.js"),
+  logger: nil
+)
+```
+
 If you'd like support for source map support, you will need to
+
 1. Add the following to your entry file, e.g, `server_rendering.js`.
 2. set `config.source_map_path`.
 
@@ -103,27 +145,11 @@ require("source-map-support").install({
   }
 });
 ```
-A [sample] webpack.config is available for reference.
-
-## The mini_racer environment.
-
-### Functions not available
-
-The following functions are **not** available in the mini_racer environment
-
-- `setTimeout`
-- `clearTimeout`
-- `setInterval`
-- `clearInterval`
-- `setImmediate`
-- `clearImmediate`
 
-### `console.log`
+See the [sample server_rendering.tsx](./sample/server_rendering.tsx) to see how
+it is integrated.
 
-`console.log` and friends (`info`, `error`, `warn`) are delegated to the
-respective methods on the configured logger.
-
-## Usage
+### Add a renderer and call `Humid.render`
 
 In your entry file, e.g, `server_rendering.js`, pass your HTML render function
 to `setHumidRenderer`. There is no need to require the function.
@@ -143,7 +169,7 @@ setHumidRenderer((json) => {
 And finally call `render` from ERB.
 
 ```ruby
-<%= Humid.render(initial_state).html_safe %>
+<%= Humid.render(MINI_RACER_CONTEXT, json).html_safe %>
 ```
 
 Instrumentation is included:
@@ -152,24 +178,49 @@ Instrumentation is included:
 Completed 200 OK in 14ms (Views: 0.2ms | Humid SSR: 11.0ms | ActiveRecord: 2.7ms)
 ```
 
-### Puma
+## The prepared `mini_racer` environment.
 
-`mini_racer` is thread safe, but not fork safe. To use with web servers that
-employ forking, use `Humid.create_context` only on forked processes. On
-production, There should be no context created on the master process.
+### Functions not available
+
+The following functions are **not** available in the mini_racer environment
+
+- `setTimeout`
+- `clearTimeout`
+- `setInterval`
+- `clearInterval`
+- `setImmediate`
+- `clearImmediate`
+
+### `console.log`
+
+`console.log` and friends (`info`, `error`, `warn`) are delegated to the
+respective methods on the configured logger.
+
+All arguments are passed through — MiniRacer converts JS objects to Ruby
+hashes and arrays automatically. A `log_formatter` proc controls how these
+arguments are formatted into a single string for the logger:
 
 ```ruby
-# Puma
-on_worker_boot do
-  Humid.create_context
-end
+Humid.configure do |config|
+  config.logger = Rails.logger
 
-on_worker_shutdown do
-  Humid.dispose
+  config.log_formatter = proc { |level, message, *rest|
+    parts = [message]
+    parts += rest.map { |a| a.is_a?(String) ? a : JSON.pretty_generate(a) }
+    parts.join("\n")
+  }
 end
 ```
 
-### Server-side libraries that detect node.js envs.
+The formatter receives `(level, message, *rest)` where:
+- `level` — the log level as a symbol (`:debug`, `:info`, `:warn`, `:error`)
+- `message` — the first argument passed to `console.log/info/warn/error`
+- `rest` — any additional arguments (objects come through as Ruby hashes/arrays)
+
+The default formatter returns `message` unchanged.
+
+## Server-side libraries that detect node.js envs.
+
 You may need webpacker to create aliases for server friendly libraries that can
 not detect the `mini_racer` environment. For example, in `webpack.config.js`.
 
@@ -187,7 +238,7 @@ not detect the `mini_racer` environment. For example, in `webpack.config.js`.
 [Vue has a resource][vue_ssr] on how to write universal code. Below
 are a few highlights that are important to keep in mind.
 
-### State
+## State
 
 Humid uses a single context across multiple request. To avoid state pollution, we
 provide a factory function to `setHumidRenderer` that builds a new app instance on
@@ -196,9 +247,9 @@ every call.
 This provides better isolation, but as it is still a shared context, polluting
 `global` is still possible. Be careful of modifying `global` in your code.
 
-### Missing browser APIs
+## Missing browser APIs
 
-Polyfills and some libraries that depend on browser APIs will fail in the
+Some libraries that depend on browser APIs will fail in the
 `mini_racer` environment because of missing browser APIs. Account for this by
 moving the `require` to `useEffect` in your component.
 
@@ -209,6 +260,71 @@ moving the `require` to `useEffect` in your component.
   }, [])
 ```
 
+## Polyfills
+
+React SSR may import node.js dependencies that you need to polyfill for. See
+a sample esbuild [build script](./sample/bulid_ssr.js) and a [shim.js](./sample/shim.js)
+to get around these issues.
+
+## Testing
+
+When running in test environments that also forks, you may need to set up new mini_racer
+contexts for each parallel worker. For example:
+
+```ruby
+ActiveSupport.on_load(:action_dispatch_integration_test) do
+  include ActionView::Helpers::TranslationHelper
+  include Devise::Test::IntegrationHelpers
+
+  parallelize_setup do
+    MINI_RACER_CONTEXT.dispose if defined?(MINI_RACER_CONTEXT)
+    ctx = MiniRacer::Context.new(timeout: 1000, ensure_gc_after_idle: 2000)
+    Object.send(:remove_const, :MINI_RACER_CONTEXT) if defined?(MINI_RACER_CONTEXT)
+    Object.const_set(:MINI_RACER_CONTEXT, Humid.prepare(ctx))
+  end
+
+  parallelize_teardown do
+    MINI_RACER_CONTEXT.dispose if defined?(MINI_RACER_CONTEXT)
+  end
+end
+```
+
+## Telemetry
+
+The `MiniRacer::Context` gives you access to V8 heap statistics for monitoring
+memory usage over time.
+
+```ruby
+MINI_RACER_CONTEXT.heap_stats
+# {:total_heap_size=>3100672,
+#  :total_heap_size_executable=>4194304,
+#  :total_physical_size=>1280640,
+#  :total_available_size=>1501560832,
+#  :used_heap_size=>1205376,
+#  :heap_size_limit=>1501560832,
+#  ...}
+```
+
+You can combine humid's instrumentation and OpenTelemetry to track heap growth
+per worker:
+
+```ruby
+meter = OpenTelemetry.meter_provider.meter("humid")
+render_histogram = meter.create_histogram("humid.render.duration", unit: "ms", description: "SSR render duration")
+heap_gauge = meter.create_gauge("humid.heap.used_bytes", unit: "By", description: "V8 heap used bytes")
+
+ActiveSupport::Notifications.subscribe("render.humid") do |event|
+  stats = MINI_RACER_CONTEXT.heap_stats
+  attributes = { "worker.pid" => Process.pid.to_s }
+
+  render_histogram.record(event.duration, attributes: attributes)
+  heap_gauge.record(stats[:used_heap_size], attributes: attributes)
+end
+```
+
+A steadily climbing `used_heap_size` across requests indicates a memory leak in
+your JavaScript bundle.
+
 ## Contributing
 
 Please see [CONTRIBUTING.md](/CONTRIBUTING.md).

data/lib/humid/controller_runtime.rb

@@ -1,4 +1,4 @@
-class Humid
+module Humid
   module ControllerRuntime
     extend ActiveSupport::Concern
 

data/lib/humid/log_subscriber.rb

@@ -1,4 +1,4 @@
-class Humid
+module Humid
   class LogSubscriber < ActiveSupport::LogSubscriber
     thread_cattr_accessor :humid_runtime
 

data/lib/humid/version.rb

@@ -1,3 +1,3 @@
-class Humid
-  VERSION = "0.1.0".freeze
+module Humid
+  VERSION = "0.5.0".freeze
 end

data/lib/humid.rb

@@ -6,106 +6,93 @@ require "humid/log_subscriber"
 require "humid/controller_runtime"
 require "humid/version"
 
-class Humid
-  @@context = nil
-
+module Humid
   class RenderError < StandardError
   end
 
   class FileNotFound < StandardError
   end
-  
-  class_attribute :config
+
+  mattr_accessor :config
 
   self.config = ActiveSupport::OrderedOptions.new.merge({
     raise_render_errors: true,
-    context_options: {},
+    log_formatter: proc { |_level, message, *_rest| message },
   })
 
-  class << self
-    def configure
-      yield config
-    end
-
-    def remove_functions
-      <<~JS
-        delete this.setTimeout;
-        delete this.setInterval;
-        delete this.clearTimeout;
-        delete this.clearInterval;
-        delete this.setImmediate;
-        delete this.clearImmediate;
-      JS
-    end
+  extend self
+  
+  def configure
+    yield self.config
+  end
 
-    def logger
-      config.logger
+  def prepare(ctx, options = {})
+    effective_config = config.merge(options)
+    logger = effective_config.logger
+    log_formatter = effective_config.log_formatter
+
+    if logger
+      fmt = log_formatter || proc { |_level, message, *_rest| message }
+      ctx.attach("console.log", proc { |*args| logger.debug(fmt.call(:debug, *args)) })
+      ctx.attach("console.info", proc { |*args| logger.info(fmt.call(:info, *args)) })
+      ctx.attach("console.error", proc { |*args| logger.error(fmt.call(:error, *args)) })
+      ctx.attach("console.warn", proc { |*args| logger.warn(fmt.call(:warn, *args)) })
     end
 
-    def renderer
-      <<~JS
-        var __renderer;
-        function setHumidRenderer(fn) {
-          __renderer = fn;
-        }
-      JS
-    end
+    js = ""
+    js << remove_functions
+    js << renderer
+    ctx.eval(js)
 
-    def context
-      @@context
-    end
+    source_path = effective_config.application_path
+    map_path = effective_config.source_map_path
 
-    def dispose
-      if @@context
-        @@context.dispose
-        @@context = nil
-      end
+    if map_path
+      ctx.attach("readSourceMap", proc { File.read(map_path) })
     end
 
-    def create_context
-      ctx = MiniRacer::Context.new(**config.context_options)
+    filename = File.basename(source_path.to_s)
+    ctx.eval(File.read(source_path), filename: filename)
 
-      if logger
-        ctx.attach("console.log", proc { |err| logger.debug(err.to_s) })
-        ctx.attach("console.info", proc { |err| logger.info(err.to_s) })
-        ctx.attach("console.error", proc { |err| logger.error(err.to_s) })
-        ctx.attach("console.warn", proc { |err| logger.warn(err.to_s) })
-      end
-
-      js = ""
-      js << remove_functions
-      js << renderer
-      ctx.eval(js)
-
-      source_path = config.application_path
-      map_path = config.source_map_path
+    ctx
+  end
 
-      if map_path
-        ctx.attach("readSourceMap", proc { File.read(map_path) })
+  def render(ctx, *args)
+    ActiveSupport::Notifications.instrument("render.humid") do
+      ctx.call("__renderer", *args)
+    rescue MiniRacer::RuntimeError => e
+      message = ([e.message] + e.backtrace.filter { |x| x.starts_with? "JavaScript" }).join("\n")
+      render_error = Humid::RenderError.new(message)
+
+      if config.raise_render_errors
+        raise render_error
+      else
+        config.logger.error(render_error.inspect)
+        ""
       end
-
-      filename = File.basename(source_path.to_s)
-      @@current_filename = filename
-      ctx.eval(File.read(source_path), filename: filename)
-
-      @@context = ctx
     end
+  end
 
-    def render(*args)
-      ActiveSupport::Notifications.instrument("render.humid") do
-        context.call("__renderer", *args)
-      rescue MiniRacer::RuntimeError => e
-        message = ([e.message] + e.backtrace.filter { |x| x.starts_with? "JavaScript" }).join("\n")
-        render_error = Humid::RenderError.new(message)
-
-        if config.raise_render_errors
-          raise render_error
-        else
-          config.logger.error(render_error.inspect)
-          ""
-        end
-      end
-    end
+  private
+  
+  def remove_functions
+    <<~JS
+      delete this.setTimeout;
+      delete this.setInterval;
+      delete this.clearTimeout;
+      delete this.clearInterval;
+      delete this.setImmediate;
+      delete this.clearImmediate;
+    JS
+  end
+
+  def renderer
+    <<~JS
+      var __renderer;
+      function setHumidRenderer(fn) {
+        __renderer = fn;
+      }
+    JS
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: humid
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Johny Ho