humid 0.2.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73079cacc72320a7c7d439d5cc443a42221a9e177dda5f25712c9898212f533a
-  data.tar.gz: f06abbe52e2e566a415d7982cac6c6313d158e1f47f2ec142179226f55d7cd63
+  metadata.gz: 961eafadcfe1132cdd132c096a28aba48155c740b224c3cbc32b4fd9731c10a6
+  data.tar.gz: 8a3635e896a4915c508a096c3b9f60e7d51265b39c6c448150fb89a627a3ab06
 SHA512:
-  metadata.gz: ce807ac8725f2054eaa15f00ecd2ec7532b5d720145f9078d211966fd3b5c81f06e282a9511778fa1ecfdcc4af028dd109ae950c14d6a9c4cb1f2c78d64bba14
-  data.tar.gz: 903b52f1aebf08c3f90d606f5e1eca7656aa04bc988d1342f863cf9a915acdc52b94d440d2f6f50c68f3d8e34f58d400c669dd7afc6f75688aad9104203e592c
+  metadata.gz: 7f9f13d45e1b4023cccdc88300c151024dbb08a5bcc73c24b1a81e089f1ad1d2a4ec1faea12feb81e13949e2c423a8e8a392d73bf45b547ecdcd20a6462b74b6
+  data.tar.gz: fba2e9ea74fdeab8a90f5503a0b34cf977ddb0006dcaf234ceff8b1d06548079461e0e5d17466cace1c68937b7fa290a5823ef0fe01352886b545b0fe87c9cc2

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,43 +68,40 @@ 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
-  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`
+## Usage
 
-```
-workers ENV.fetch("WEB_CONCURRENCY") { 1 }
+### Set a renderer
 
-on_worker_boot do
-  Humid.create_context
-end
+In your entry file, e.g, `server_rendering.js` (specified in
+`config.application_path`), pass your HTML render function to
+`setHumidRenderer`. There is no need to require the function, its included in
+the environment.
 
-on_worker_shutdown do
-  Humid.dispose
-end
+```javascript
+// Set a factory function that will create a new instance of our app
+// for each request.
+setHumidRenderer((json) => {
+  const initialState = JSON.parse(json)
+
+  return ReactDOMServer.renderToString(
+    <Application initialPage={initialState}/>
+  )
+})
 ```
 
-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`.
+If you'd like support for source map support, you will need to add the following
+to the same file and set `config.source_map_path` like the configuration above.
 
 ```javascript
 require("source-map-support").install({
@@ -103,9 +113,60 @@ require("source-map-support").install({
   }
 });
 ```
-A [sample] webpack.config is available for reference.
 
-## The mini_racer environment.
+### Your webserver
+
+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.**
+
+For example with puma:
+
+```ruby
+# config/puma.rb
+on_worker_boot do
+  ctx = MiniRacer::Context.new(timeout: 100, ensure_gc_after_idle: 2000)
+  
+  MINI_RACER_CONTEXT = Humid.prepare(ctx)
+end
+
+on_worker_shutdown do
+  MINI_RACER_CONTEXT.dispose
+end
+```
+
+`Humid.prepare` will prepare the context's
+[environment](#the-mini_racer-environment).
+
+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
+)
+```
+
+See the [sample server_rendering.tsx](./sample/server_rendering.tsx) to see how
+it is integrated.
+
+### Call `Humid.render`
+
+And finally call `render` from ERB.
+
+```ruby
+<%= Humid.render(MINI_RACER_CONTEXT, json).html_safe %>
+```
+
+Instrumentation is included:
+
+```
+Completed 200 OK in 14ms (Views: 0.2ms | Humid SSR: 11.0ms | ActiveRecord: 2.7ms)
+```
+
+## The `mini_racer` environment
 
 ### Functions not available
 
@@ -144,55 +205,10 @@ The formatter receives `(level, message, *rest)` where:
 - `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 simply returns `message` unchanged.
-
-## Usage
+The default formatter returns `message` unchanged.
 
-In your entry file, e.g, `server_rendering.js`, pass your HTML render function
-to `setHumidRenderer`. There is no need to require the function.
+## Server-side libraries that detect node.js envs.
 
-```javascript
-// Set a factory function that will create a new instance of our app
-// for each request.
-setHumidRenderer((json) => {
-  const initialState = JSON.parse(json)
-
-  return ReactDOMServer.renderToString(
-    <Application initialPage={initialState}/>
-  )
-})
-```
-
-And finally call `render` from ERB.
-
-```ruby
-<%= Humid.render(initial_state).html_safe %>
-```
-
-Instrumentation is included:
-
-```
-Completed 200 OK in 14ms (Views: 0.2ms | Humid SSR: 11.0ms | ActiveRecord: 2.7ms)
-```
-
-### Puma
-
-`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.
-
-```ruby
-# Puma
-on_worker_boot do
-  Humid.create_context
-end
-
-on_worker_shutdown do
-  Humid.dispose
-end
-```
-
-### 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`.
 
@@ -210,7 +226,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
@@ -219,9 +235,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.
 
@@ -232,6 +248,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.2.0".freeze
+module Humid
+  VERSION = "0.6.0".freeze
 end

data/lib/humid.rb

@@ -6,108 +6,101 @@ 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
+
+  class NotPrepared < StandardError
+  end
+
+  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 = remove_functions + 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
-        fmt = config.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
-
-      js = ""
-      js << remove_functions
-      js << renderer
-      ctx.eval(js)
+    def ctx.humid_prepared?
+      true
+    end
 
-      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)
+    is_prepared = ctx.respond_to?(:humid_prepared?) && ctx.humid_prepared?
+    raise Humid::NotPrepared, "Context was not prepared with Humid.prepare" unless is_prepared
+
+    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.2.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Johny Ho
@@ -37,7 +37,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '8.0'
-description: Javascript SSR rendering for Rails
+description: Javascript Server Side Rendering (SSR) for Rails
 email: jho406@gmail.com
 executables: []
 extensions: []
@@ -68,5 +68,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Javascript SSR rendering for Rails
+summary: Javascript Server Side Rendering (SSR) for Rails
 test_files: []