inertia_hanami 0.1.0

data/lib/inertia_hanami/protocol_builder.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module InertiaHanami
+  # Decides which props actually go into an Inertia response: applies the
+  # partial-reload algorithm (only/except/reset dot-paths), the AlwaysProp
+  # bypass, the Optional/Defer exclusion-by-default rule, and Once-prop
+  # caching, then collects the deferredProps/mergeProps/prependProps/
+  # deepMergeProps/matchPropsOn/onceProps/scrollProps metadata the client
+  # needs.
+  #
+  # Operates on the already-evaluated output of PropEvaluator (a Hash whose
+  # leaves are plain values or Props::Base instances with resolved,
+  # argument-free blocks) plus plain Ruby values for the partial-reload
+  # headers, so it stays framework/header-parsing free.
+  #
+  # Ported from inertia-rails' props_resolver.rb algorithm (inertia-rage's
+  # protocol_builder.rb, the originally intended porting source, isn't
+  # available as a dependency here), adapted to this repo's Data-based Props
+  # wrappers.
+  # rubocop:disable Metrics/ClassLength -- one small dedicated transform_* method per prop type
+  class ProtocolBuilder
+    # Sentinel returned by #transform to signal a filtered-out prop, so a
+    # Hash node can tell "excluded" apart from a legitimately nil value.
+    DROP = Object.new.freeze
+    private_constant :DROP
+
+    # `partial` bundles the X-Inertia-Partial-* / X-Inertia-Reset /
+    # X-Inertia-Except-Once-Props / X-Inertia-Infinite-Scroll-Merge-Intent
+    # header values (already split into arrays by the caller, except
+    # :scroll_intent which is a single raw value): :component, :only,
+    # :except, :reset, :except_once, :scroll_intent.
+    def initialize(component:, props:, partial: {})
+      @component = component
+      @props = props
+      assign_partial(partial)
+      @deferred_props = Hash.new { |hash, key| hash[key] = [] }
+      @merge_props = []
+      @prepend_props = []
+      @deep_merge_props = []
+      @match_props_on = []
+      @once_props = {}
+      @scroll_props = {}
+    end
+
+    def call
+      {
+        props: transform(@props, []),
+        deferredProps: presence(@deferred_props.transform_values(&:sort)),
+        mergeProps: presence(@merge_props),
+        prependProps: presence(@prepend_props),
+        deepMergeProps: presence(@deep_merge_props),
+        matchPropsOn: presence(@match_props_on),
+        onceProps: presence(@once_props),
+        scrollProps: presence(@scroll_props)
+      }.compact
+    end
+
+    private
+
+    def assign_partial(partial)
+      @partial = !partial[:component].nil? && partial[:component] == @component
+      @only = partial[:only] || []
+      @except = partial[:except] || []
+      @reset = partial[:reset] || []
+      @except_once = partial[:except_once] || []
+      @scroll_intent = partial[:scroll_intent] || "append"
+    end
+
+    # Maps a node's class to the transform method that handles it, so
+    # #transform stays a flat dispatch instead of an if/elsif chain.
+    TRANSFORMERS = {
+      Props::Once => :transform_once,
+      Props::Scroll => :transform_scroll,
+      Props::Merge => :transform_merge,
+      Props::Defer => :transform_defer,
+      Props::Optional => :transform_optional
+    }.freeze
+    private_constant :TRANSFORMERS
+
+    def transform(node, path)
+      return transform_hash(node, path) if node.is_a?(Hash)
+      return node.resolve if node.is_a?(Props::Always)
+
+      transformer = TRANSFORMERS[node.class]
+      return send(transformer, node, path) if transformer
+
+      transform_plain(node, path)
+    end
+
+    def transform_hash(node, path)
+      node.each_with_object({}) do |(key, value), acc|
+        resolved = transform(value, path + [key.to_s])
+        acc[key] = resolved unless resolved == DROP
+      end
+    end
+
+    def transform_plain(node, path)
+      keep_prop?(path) ? node : DROP
+    end
+
+    def transform_optional(node, path)
+      keep_default_excluded?(path) ? node.resolve : DROP
+    end
+
+    def transform_defer(node, path)
+      return node.resolve if keep_default_excluded?(path)
+
+      @deferred_props[node.group] << path.join(".")
+      DROP
+    end
+
+    def transform_merge(node, path)
+      return DROP unless keep_prop?(path)
+
+      dot_path = path.join(".")
+      (node.deep_merge ? @deep_merge_props : @merge_props) << dot_path
+      @match_props_on << "#{dot_path}.#{node.match_on}" if node.match_on
+      node.resolve
+    end
+
+    def transform_once(node, path)
+      dot_path = path.join(".")
+      key = node.key || dot_path
+      return DROP if once_cache_hit?(node, dot_path, key)
+      return DROP unless keep_prop?(path)
+
+      @once_props[key] = { "prop" => dot_path, "expiresAt" => node.expires_at }.compact
+      node.resolve
+    end
+
+    def once_cache_hit?(node, dot_path, key)
+      reset_requested = @reset.include?(dot_path) || @reset.include?(key)
+      already_cached = !node.fresh && (@except_once.include?(key) || @except_once.include?(dot_path))
+      !reset_requested && already_cached
+    end
+
+    def transform_scroll(node, path)
+      return DROP unless keep_prop?(path)
+
+      dot_path = path.join(".")
+      (@scroll_intent == "prepend" ? @prepend_props : @merge_props) << dot_path
+      @match_props_on << "#{dot_path}.#{node.match_on}" if node.match_on
+      @scroll_props[dot_path] = scroll_metadata(node, dot_path)
+      node.resolve
+    end
+
+    def scroll_metadata(node, dot_path)
+      {
+        "pageName" => node.page_name,
+        "previousPage" => node.previous_page,
+        "nextPage" => node.next_page,
+        "currentPage" => node.current_page,
+        "reset" => @reset.include?(dot_path)
+      }
+    end
+
+    # Optional/Defer: only included when a partial reload explicitly names
+    # them via `only`, subject to `except` on top.
+    def keep_default_excluded?(path)
+      return false unless @partial
+      return false if @only.empty? || !path_matches?(path, @only)
+
+      !excluded_by_except?(path)
+    end
+
+    # Plain values/Merge/Once: excluded by `except`, or by a non-empty
+    # `only` during a partial reload that doesn't match this path.
+    def keep_prop?(path)
+      return false if excluded_by_except?(path)
+      return true unless @partial && !@only.empty?
+
+      path_matches?(path, @only)
+    end
+
+    def excluded_by_except?(path)
+      @partial && !@except.empty? && path_matches?(path, @except)
+    end
+
+    # A dot-path matches a set entry if it's equal to it, a descendant of it
+    # (the entry names an ancestor group), or an ancestor of it (walking
+    # through an intermediate node on the way to a deeper match).
+    def path_matches?(path, set)
+      dot_path = path.join(".")
+      set.any? do |entry|
+        entry == dot_path || dot_path.start_with?("#{entry}.") || entry.start_with?("#{dot_path}.")
+      end
+    end
+
+    def presence(collection)
+      collection.nil? || collection.empty? ? nil : collection
+    end
+  end
+  # rubocop:enable Metrics/ClassLength
+end

data/lib/inertia_hanami/provider.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "hanami"
+require "dry/system"
+require "hanami/provider/source"
+
+module InertiaHanami
+  class Provider < Hanami::Provider::Source
+    def prepare
+      require "inertia_hanami/configuration"
+      require "inertia_hanami/asset_version"
+    end
+
+    def start
+      configuration = InertiaHanami::Configuration.new
+
+      if configuration.config.version.nil?
+        configuration.config.version = InertiaHanami::AssetVersion.digest(assets_root)
+      end
+
+      register("config", configuration.config)
+    end
+
+    private
+
+    def assets_root
+      return nil unless target.container.providers.key?(:assets)
+
+      target.start(:assets)
+      target[:assets].root
+    end
+  end
+end

data/lib/inertia_hanami/renderer.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "json"
+
+module InertiaHanami
+  # Builds the Inertia page envelope and decides whether to answer an
+  # Inertia XHR request directly (JSON body) or to hand the page off to
+  # Hanami's normal rendering pipeline for the initial full-page load
+  # (HTML, via the layout's `inertia_root(page:)` helper).
+  #
+  # Expects `props` to already be evaluated (see PropEvaluator) - this class
+  # only applies the partial-reload/prop-filtering algorithm (via
+  # ProtocolBuilder) and shapes the resulting envelope.
+  class Renderer
+    def initialize(request:, response:, component:, props: {}, url: nil, version: nil,
+                    encrypt_history: false, clear_history: false)
+      @request = request
+      @response = response
+      @component = component
+      @props = props
+      @url = url || request.fullpath
+      @version = version
+      @encrypt_history = encrypt_history
+      @clear_history = clear_history
+      @request_context = RequestContext.new(request.env)
+    end
+
+    def render
+      request_context.inertia? ? render_inertia_response : render_initial_load
+    end
+
+    private
+
+    attr_reader :request_context
+
+    def render_inertia_response
+      @response.headers["X-Inertia"] = "true"
+      @response.format = :json
+      @response.body = page.to_json
+    end
+
+    def render_initial_load
+      if ssr_enabled?
+        result = SSRRenderer.instance.call(page)
+        if result
+          @response[:ssr_head] = result.head
+          @response[:ssr_body] = result.body
+          return
+        end
+      end
+
+      @response[:page] = page
+    end
+
+    def ssr_enabled?
+      Hanami.app["inertia.config"].ssr.enabled
+    end
+
+    def page
+      @page ||= build_page
+    end
+
+    def build_page
+      resolved = ProtocolBuilder.new(
+        component: @component,
+        props: @props,
+        partial: request_context.partial_params
+      ).call
+
+      {
+        "component" => @component,
+        "props" => resolved[:props],
+        "url" => @url,
+        "version" => @version,
+        "encryptHistory" => @encrypt_history,
+        "clearHistory" => @clear_history
+      }.merge(metadata(resolved))
+    end
+
+    def metadata(resolved)
+      {
+        "deferredProps" => resolved[:deferredProps],
+        "mergeProps" => resolved[:mergeProps],
+        "prependProps" => resolved[:prependProps],
+        "deepMergeProps" => resolved[:deepMergeProps],
+        "matchPropsOn" => resolved[:matchPropsOn],
+        "onceProps" => resolved[:onceProps],
+        "scrollProps" => resolved[:scrollProps]
+      }.compact
+    end
+  end
+end

data/lib/inertia_hanami/request_context.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module InertiaHanami
+  # Parses the Inertia protocol's request headers off a Rack env: detection
+  # (X-Inertia), the asset version the client has cached (X-Inertia-Version),
+  # the partial-reload headers (X-Inertia-Partial-Component,
+  # X-Inertia-Partial-Data, X-Inertia-Partial-Except, X-Inertia-Reset,
+  # X-Inertia-Except-Once-Props), and the infinite-scroll merge-intent header
+  # (X-Inertia-Infinite-Scroll-Merge-Intent).
+  #
+  # Stays framework/Hanami-request free (plain Rack env in, plain values out)
+  # so it can be constructed from anywhere a Rack env is available.
+  class RequestContext
+    def initialize(env)
+      @env = env
+    end
+
+    def inertia?
+      @env["HTTP_X_INERTIA"] == "true"
+    end
+
+    def version
+      @env["HTTP_X_INERTIA_VERSION"]
+    end
+
+    def partial_component
+      @env["HTTP_X_INERTIA_PARTIAL_COMPONENT"]
+    end
+
+    def partial?
+      !partial_component.nil?
+    end
+
+    def partial_only
+      split_header("HTTP_X_INERTIA_PARTIAL_DATA")
+    end
+
+    def partial_except
+      split_header("HTTP_X_INERTIA_PARTIAL_EXCEPT")
+    end
+
+    def reset
+      split_header("HTTP_X_INERTIA_RESET")
+    end
+
+    def except_once
+      split_header("HTTP_X_INERTIA_EXCEPT_ONCE_PROPS")
+    end
+
+    def scroll_intent
+      @env["HTTP_X_INERTIA_INFINITE_SCROLL_MERGE_INTENT"]
+    end
+
+    # Shaped to feed directly into ProtocolBuilder.new(partial: ...).
+    def partial_params
+      {
+        component: partial_component,
+        only: partial_only,
+        except: partial_except,
+        reset: reset,
+        except_once: except_once,
+        scroll_intent: scroll_intent
+      }
+    end
+
+    private
+
+    def split_header(key)
+      value = @env[key]
+      return [] if value.nil? || value.empty?
+
+      value.split(",").map(&:strip).reject(&:empty?)
+    end
+  end
+end

data/lib/inertia_hanami/ssr_renderer.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "digest"
+require "json"
+
+module InertiaHanami
+  # POSTs the Inertia page envelope to a separately-run Node SSR server and
+  # splices the returned markup into the layout in place of the CSR div
+  # (see Helper#inertia_ssr_head / #inertia_ssr_body).
+  #
+  # Responses are memoized in-process, keyed by a SHA256 digest of the page
+  # JSON, so repeat renders of an unchanged page skip the HTTP round-trip.
+  # The cache is a plain in-memory Hash - it is per-process and unbounded,
+  # not shared across app instances.
+  #
+  # On any failure (connection error, non-2xx response, malformed JSON),
+  # #call returns nil so the caller can fall back to CSR, unless
+  # `ssr.raise_on_error` is enabled, in which case the error propagates.
+  class SSRRenderer
+    Result = Struct.new(:head, :body)
+
+    def self.instance
+      @instance ||= new
+    end
+
+    def initialize(config: Hanami.app["inertia.config"])
+      @config = config
+      @cache = {}
+      @mutex = Mutex.new
+    end
+
+    def call(page)
+      json = page.to_json
+      digest = Digest::SHA256.hexdigest(json)
+
+      @mutex.synchronize { @cache[digest] } || fetch(json, digest)
+    end
+
+    private
+
+    def fetch(json, digest)
+      result = Result.new(*parse(post(json)).values_at("head", "body"))
+      result.head = Array(result.head).join("\n") if result.head.is_a?(Array)
+      @mutex.synchronize { @cache[digest] = result }
+      result
+    rescue StandardError => e
+      raise e if @config.ssr.raise_on_error
+
+      nil
+    end
+
+    def post(json)
+      uri = URI.join(@config.ssr.url, "/render")
+      response = Net::HTTP.post(uri, json, "Content-Type" => "application/json")
+      raise "SSR server responded with #{response.code}" unless response.is_a?(Net::HTTPSuccess)
+
+      response.body
+    end
+
+    def parse(body)
+      JSON.parse(body)
+    end
+  end
+end