inertia_hanami 0.1.0

data/lib/generators/inertia_hanami/templates/sample_action.rb.erb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module <%= namespace %>
+  module Actions
+    module InertiaExample
+      class Show < <%= namespace %>::Action
+        include InertiaHanami::Action
+
+        def handle(_request, _response)
+          inertia_render("InertiaExample/Show", props: { greeting: "Hello from inertia_hanami" })
+        end
+      end
+    end
+  end
+end

data/lib/generators/inertia_hanami/templates/sample_template.html.erb.erb

@@ -0,0 +1 @@
+<%%# Inertia renders this page client-side; the layout's inertia_root(page:) carries the data. %>

data/lib/generators/inertia_hanami/templates/sample_view.rb.erb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module <%= namespace %>
+  module Views
+    module InertiaExample
+      class Show < <%= namespace %>::View
+        expose :page, layout: true
+        expose :ssr_head, layout: true
+        expose :ssr_body, layout: true
+      end
+    end
+  end
+end

data/lib/inertia_hanami/action.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module InertiaHanami
+  # Include-able into `Hanami::Action` subclasses to speak the Inertia
+  # protocol: skips Hanami's automatic view rendering for Inertia XHR
+  # requests, renders the Inertia page envelope, accumulates shared props,
+  # and handles the external-redirect (409 + X-Inertia-Location) case.
+  #
+  # Follows Hanami's own composition idiom (`include Inertia::Action`)
+  # rather than requiring a subclass of a framework-specific base class.
+  module Action
+    # Session key used to stash validation errors across a redirect, mirroring
+    # inertia-rails' `session[:inertia_errors]`. Cleared as soon as it's read
+    # into the next response's `errors` prop.
+    INERTIA_ERRORS_SESSION_KEY = "inertia_errors"
+
+    def self.included(action_class)
+      super
+
+      action_class.extend(ClassMethods)
+      action_class.include(InstanceMethods)
+
+      action_class.append_before do |req, res|
+        @inertia_context[:request] = req
+        @inertia_context[:response] = res
+      end
+
+      share_errors_and_flash(action_class)
+    end
+
+    # Auto-shared on every request: `errors` (from the session, stashed via
+    # `share_inertia_errors`) and `flash` (from Hanami's flash). Registered
+    # before any `inertia_share` calls in the including class's own body, so
+    # those can override either key. No-ops entirely when the app hasn't
+    # enabled sessions (`session_enabled?` defaults to `false` on
+    # `Hanami::Action`).
+    def self.share_errors_and_flash(action_class)
+      action_class.inertia_share do
+        next {} unless session_enabled?
+
+        { errors: inertia_errors_prop, flash: inertia_flash_prop }.compact
+      end
+    end
+    private_class_method :share_errors_and_flash
+
+    # Class-level `inertia_share` macro, inherited down subclasses.
+    module ClassMethods
+      def inertia_shared_props
+        inherited_inertia_shared_props.merge(@inertia_shared_props ||= {})
+      end
+
+      def inertia_shared_blocks
+        inherited_inertia_shared_blocks + (@inertia_shared_blocks ||= [])
+      end
+
+      def inertia_share(**props, &block)
+        (@inertia_shared_props ||= {}).merge!(props)
+        (@inertia_shared_blocks ||= []) << block if block
+      end
+
+      # Class-level default for whether pages rendered by this action (and
+      # its subclasses, unless they override it) should have their Inertia
+      # history entry encrypted client-side. Falls back to the global
+      # `Hanami.app["inertia.config"].encrypt_history` default when unset
+      # anywhere in the ancestry (see `inertia_encrypt_history?`).
+      def encrypt_history(value: true)
+        @inertia_encrypt_history = value
+      end
+
+      def inertia_encrypt_history?
+        return @inertia_encrypt_history if defined?(@inertia_encrypt_history)
+
+        inherited_inertia_encrypt_history?
+      end
+
+      private
+
+      def inherited_inertia_shared_props
+        superclass.respond_to?(:inertia_shared_props) ? superclass.inertia_shared_props : {}
+      end
+
+      def inherited_inertia_shared_blocks
+        superclass.respond_to?(:inertia_shared_blocks) ? superclass.inertia_shared_blocks : []
+      end
+
+      def inherited_inertia_encrypt_history?
+        superclass.respond_to?(:inertia_encrypt_history?) ? superclass.inertia_encrypt_history? : nil
+      end
+    end
+
+    # Instance-level Inertia API mixed into the including action class.
+    module InstanceMethods
+      # Runs before the object is frozen (Hanami::Action freezes instances at
+      # the end of #initialize), so @inertia_context can hold a mutable Hash
+      # to stash the request/response for later use by frozen instance methods.
+      #
+      # Deliberately `(**kwargs)` and not `(...)`: dry-auto_inject's
+      # MethodParameters treats `(...)` as a full signature rather than a
+      # pass-through to skip past (mirroring ROM's delegation convention), so
+      # with `(...)` it stops here instead of reaching `Hanami::Action#initialize`
+      # - any `Deps[]` dependency keyword then gets forwarded all the way down
+      # and rejected as unknown. `(**kwargs)` is recognized as pass-through.
+      def initialize(**kwargs)
+        @inertia_context = {}
+        super(**kwargs)
+      end
+
+      def auto_render?(res)
+        return false if RequestContext.new(res.env).inertia?
+
+        super
+      end
+
+      def inertia_share(**props, &block)
+        instance_props = (@inertia_context[:instance_shared_props] ||= {})
+        instance_props.merge!(props)
+        (@inertia_context[:instance_shared_blocks] ||= []) << block if block
+      end
+
+      # Instance-level override of the class's `encrypt_history` default,
+      # for a single action instance.
+      def encrypt_history(value: true)
+        @inertia_context[:instance_encrypt_history] = value
+      end
+
+      # Marks the next `inertia_render` call's response as `clearHistory:
+      # true`, telling the client to wipe any encrypted history it has
+      # stored (e.g. call this before redirecting on logout).
+      def clear_history
+        @inertia_context[:instance_clear_history] = true
+      end
+
+      def inertia_render(component, props: {}, url: nil, version: nil,
+                         encrypt_history: inertia_history_encrypted?, clear_history: inertia_history_cleared?)
+        Renderer.new(
+          request: @inertia_context[:request],
+          response: @inertia_context[:response],
+          component: component,
+          props: inertia_collected_props.merge(props),
+          url: url,
+          version: version || Hanami.app["inertia.config"].version,
+          encrypt_history: encrypt_history,
+          clear_history: clear_history
+        ).render
+      end
+
+      def inertia_location(url)
+        request = @inertia_context[:request]
+        response = @inertia_context[:response]
+
+        if RequestContext.new(request.env).inertia?
+          response.headers["X-Inertia-Location"] = url
+          halt(409)
+        else
+          response.redirect_to(url)
+        end
+      end
+
+      # Stashes `errors` in the session so they surface as the `errors` prop
+      # on the next request's Inertia page (e.g. after a validation failure
+      # redirect). Analogous to inertia-rails' `redirect_to ..., inertia: {
+      # errors: ... }`.
+      def share_inertia_errors(errors)
+        hash = errors.respond_to?(:to_h) ? errors.to_h : errors
+        @inertia_context[:request].session[INERTIA_ERRORS_SESSION_KEY] = hash
+      end
+
+      private
+
+      def inertia_history_encrypted?
+        instance_value = @inertia_context[:instance_encrypt_history]
+        return instance_value unless instance_value.nil?
+
+        class_value = self.class.inertia_encrypt_history?
+        return class_value unless class_value.nil?
+
+        Hanami.app["inertia.config"].encrypt_history
+      end
+
+      def inertia_history_cleared?
+        @inertia_context[:instance_clear_history] || false
+      end
+
+      def inertia_collected_props
+        props = self.class.inertia_shared_props.dup
+        self.class.inertia_shared_blocks.each { |block| props.merge!(instance_exec(&block)) }
+        props.merge!(@inertia_context[:instance_shared_props]) if @inertia_context[:instance_shared_props]
+        (@inertia_context[:instance_shared_blocks] || []).each { |block| props.merge!(instance_exec(&block)) }
+        props
+      end
+
+      # Reads and clears any errors stashed via `share_inertia_errors`, so
+      # they're delivered exactly once. Falls back to an empty hash when
+      # `always_include_errors_hash` is enabled, or is omitted (nil) entirely
+      # otherwise.
+      def inertia_errors_prop
+        stashed = @inertia_context[:request].session.delete(INERTIA_ERRORS_SESSION_KEY)
+        return Props::Always.new(block: -> { stashed }) if stashed
+
+        return nil unless Hanami.app["inertia.config"].always_include_errors_hash
+
+        Props::Always.new(block: -> { {} })
+      end
+
+      # Shares the current request's flash messages, when there are any.
+      def inertia_flash_prop
+        flash = @inertia_context[:response].flash.now
+        return nil if flash.empty?
+
+        Props::Always.new(block: -> { flash })
+      end
+    end
+  end
+end

data/lib/inertia_hanami/asset_version.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "digest"
+require "pathname"
+
+module InertiaHanami
+  # Derives an Inertia asset version string from hanami-assets' assets.json
+  # manifest, mirroring the role ViteRuby.digest plays for inertia-rails.
+  module AssetVersion
+    MANIFEST_FILENAME = "assets.json"
+
+    # Returns a SHA256 hex digest of the assets.json manifest under `assets_root`,
+    # or nil if no manifest is present (e.g. assets not yet compiled).
+    def self.digest(assets_root)
+      return nil if assets_root.nil?
+
+      manifest_path = Pathname(assets_root).join(MANIFEST_FILENAME)
+      return nil unless manifest_path.file?
+
+      Digest::SHA256.file(manifest_path).hexdigest
+    end
+  end
+end

data/lib/inertia_hanami/cli/commands/install.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "generators/inertia_hanami/install_generator"
+
+module InertiaHanami
+  module CLI
+    module Commands
+      # `hanami generate inertia:install` - scaffolds the provider, middleware
+      # wiring, layout, view helper, and a sample page for inertia_hanami.
+      class Install < Hanami::CLI::Commands::App::Command
+        option :force, type: :flag, default: false, desc: "Overwrite existing files during generation"
+        option :framework, default: "react", values: InertiaHanami::Generators::InstallGenerator::FRAMEWORK_PACKAGES.keys,
+                           desc: "Frontend framework for @inertiajs/* package.json guidance"
+
+        example [
+          %(               (scaffolds provider, layout, helper, sample page, react npm guidance)),
+          %(--framework=vue (npm guidance targets @inertiajs/vue3 instead)),
+          %(--force         (overwrite files this command previously generated))
+        ]
+
+        def call(force:, framework:, **)
+          InertiaHanami::Generators::InstallGenerator.new(
+            fs: fs, inflector: inflector, out: out
+          ).call(base_path: app.root, namespace: app.namespace, framework: framework, force: force)
+        end
+      end
+    end
+  end
+end

data/lib/inertia_hanami/cli.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# Registers `hanami generate inertia:install` with the Hanami CLI.
+#
+# Only loaded when `Hanami::CLI` is already defined (see
+# `inertia_hanami.rb`) - i.e. when this gem is required from Bundler's
+# `:cli` group, the same convention `hanami-reloader` and `hanami-rspec`
+# use to hook into `hanami generate`/`hanami server` without hanami-cli
+# needing to know about third-party gems in advance.
+
+require "hanami/cli"
+require "inertia_hanami/cli/commands/install"
+
+if Hanami::CLI.within_hanami_app?
+  Hanami::CLI.register("generate inertia:install", InertiaHanami::CLI::Commands::Install)
+end

data/lib/inertia_hanami/configuration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "dry/configurable"
+
+module InertiaHanami
+  class Configuration
+    include Dry::Configurable
+
+    setting :version, default: nil
+    setting :root_view, default: "app"
+    setting :root_dom_id, default: "app"
+    setting :component_path_resolver, default: ->(component) { component }
+    setting :always_include_errors_hash, default: false
+    setting :encrypt_history, default: false
+
+    setting :ssr do
+      setting :enabled, default: false
+      setting :url, default: "http://localhost:13714"
+      setting :raise_on_error, default: false
+    end
+  end
+end

data/lib/inertia_hanami/helper.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "json"
+require "hanami/view/html"
+
+module InertiaHanami
+  # View helper that renders the Inertia root element for the initial
+  # full-page load. Include into a view/scope class, or call directly from
+  # an ERB template/layout.
+  module Helper
+    module_function
+
+    # Renders a `<script data-page="app" type="application/json">` tag
+    # holding the page JSON, plus the empty `<div id="app">` mount point.
+    # `@inertiajs/react|vue3|svelte`'s `createInertiaApp` (since Inertia
+    # v3) only reads the initial page from that script tag - it no longer
+    # falls back to a `data-page` attribute on the mount div - so this is
+    # the only form current clients will actually pick up.
+    def inertia_root(page:, id: nil)
+      root_id = CGI.escapeHTML((id || Hanami.app["inertia.config"].root_dom_id).to_s)
+      # Marked html_safe so Hanami::View's ERB engine doesn't re-escape the
+      # tags themselves. A `<script>` element's content is raw text per the
+      # HTML parsing spec - entities inside it are never decoded - so the
+      # JSON must NOT be HTML-entity-escaped (that would corrupt it before
+      # JSON.parse ever sees it); the only real risk is a literal
+      # `</script` sequence prematurely closing the tag, guarded separately.
+      <<~HTML.html_safe
+        <script data-page="#{root_id}" type="application/json">#{escape_script_content(page.to_json)}</script>
+        <div id="#{root_id}"></div>
+      HTML
+    end
+
+    def escape_script_content(json)
+      json.gsub("</", '<\/')
+    end
+
+    # Renders the `<head>` markup returned by the SSR server. Belongs inside
+    # the layout's `<head>` tag.
+    def inertia_ssr_head(head)
+      head.to_s.html_safe
+    end
+
+    # Renders the `<body>` markup returned by the SSR server, in place of
+    # the CSR `inertia_root` div.
+    def inertia_ssr_body(body)
+      body.to_s.html_safe
+    end
+  end
+end

data/lib/inertia_hanami/middleware/csrf.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "rack/request"
+require "rack/utils"
+
+module InertiaHanami
+  module Middleware
+    # Bridges Inertia's client-side CSRF handshake to Hanami's own
+    # Hanami::Action::CSRFProtection, without reimplementing either side:
+    #
+    # - Inertia's HTTP client automatically reads an XSRF-TOKEN cookie and
+    #   echoes it back as an X-XSRF-TOKEN header on every request.
+    # - Hanami::Action::CSRFProtection stores its challenge token in the
+    #   session and only checks for it via the `_csrf_token` param or an
+    #   X-CSRF-Token header — it never exposes the token as a cookie.
+    #
+    # This middleware translates between the two: an incoming X-XSRF-TOKEN
+    # header is copied into X-CSRF-Token before the request reaches the
+    # action, and once the action has minted/reused the session's CSRF
+    # token, it's mirrored into a readable XSRF-TOKEN cookie on the way out.
+    class Csrf
+      COOKIE_NAME = "XSRF-TOKEN"
+      # Hanami::Action::Request::Session#[]= always stringifies keys before
+      # writing to the underlying rack.session store, regardless of the
+      # symbol Hanami::Action::CSRFProtection itself indexes with - so the
+      # token lands under this string key, not :_csrf_token.
+      SESSION_KEY = "_csrf_token"
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        bridge_incoming_token(env)
+
+        status, headers, body = @app.call(env)
+
+        expose_outgoing_token(env, headers)
+
+        [status, headers, body]
+      end
+
+      private
+
+      def bridge_incoming_token(env)
+        token = env["HTTP_X_XSRF_TOKEN"]
+        env["HTTP_X_CSRF_TOKEN"] ||= token if token
+      end
+
+      def expose_outgoing_token(env, headers)
+        session = env["rack.session"]
+        token = session && session[SESSION_KEY]
+        return unless token
+
+        request = Rack::Request.new(env)
+        Rack::Utils.set_cookie_header!(
+          headers, COOKIE_NAME,
+          { value: token, path: "/", secure: request.ssl?, same_site: :lax }
+        )
+      end
+    end
+  end
+end

data/lib/inertia_hanami/middleware/redirects.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "rack/request"
+require "uri"
+
+module InertiaHanami
+  module Middleware
+    # Plain Rack middleware implementing the Inertia protocol's redirect
+    # mechanics:
+    #
+    # - 301/302 redirects issued in response to a PUT/PATCH/DELETE request are
+    #   rewritten to 303, so the client's follow-up GET doesn't resubmit the
+    #   original request body.
+    # - Redirects to an external origin are rewritten to a 409 response with
+    #   an X-Inertia-Location header instead of a normal redirect, since
+    #   Inertia's XHR-driven visits can't follow cross-origin redirects
+    #   themselves; the client reads that header and performs a full
+    #   browser visit instead.
+    #
+    # Both rewrites only apply to Inertia requests (X-Inertia header) —
+    # ordinary browser navigations are left untouched.
+    class Redirects
+      REWRITTEN_STATUSES = [301, 302].freeze
+      BODY_RESUBMITTING_METHODS = %w[PUT PATCH DELETE].freeze
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        status, headers, body = @app.call(env)
+
+        request_context = RequestContext.new(env)
+        return [status, headers, body] unless request_context.inertia?
+
+        location = headers["Location"] || headers["location"]
+        return [status, headers, body] unless redirect?(status) && location
+
+        if external?(env, location)
+          return [409, { "X-Inertia-Location" => location }, [""]]
+        end
+
+        if REWRITTEN_STATUSES.include?(status) && BODY_RESUBMITTING_METHODS.include?(env["REQUEST_METHOD"])
+          status = 303
+        end
+
+        [status, headers, body]
+      end
+
+      private
+
+      def redirect?(status)
+        status.to_i.between?(300, 399)
+      end
+
+      def external?(env, location)
+        target = URI.parse(location)
+        return false if target.host.nil?
+
+        request = Rack::Request.new(env)
+        target.scheme != request.scheme || target.host != request.host || target.port != request.port
+      rescue URI::InvalidURIError
+        false
+      end
+    end
+  end
+end

data/lib/inertia_hanami/middleware/version.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "rack/request"
+
+module InertiaHanami
+  module Middleware
+    # Plain Rack middleware implementing the Inertia protocol's asset
+    # versioning handshake: on a GET Inertia request whose X-Inertia-Version
+    # header doesn't match the server's configured version, respond with a
+    # 409 + X-Inertia-Location (empty body) instead of calling downstream,
+    # so the client performs a full browser visit and picks up new assets.
+    class Version
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        request_context = RequestContext.new(env)
+
+        if stale?(env, request_context)
+          request = Rack::Request.new(env)
+          return [409, { "X-Inertia-Location" => request.url }, [""]]
+        end
+
+        @app.call(env)
+      end
+
+      private
+
+      def stale?(env, request_context)
+        env["REQUEST_METHOD"] == "GET" &&
+          request_context.inertia? &&
+          request_context.version != Hanami.app["inertia.config"].version
+      end
+    end
+  end
+end

data/lib/inertia_hanami/prop_evaluator.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module InertiaHanami
+  # Resolves a props structure (plain values, Procs, Props::Base wrappers, and
+  # nested hashes thereof) against a Hanami action instance, so prop blocks can
+  # access the action's params/session/deps via instance_exec.
+  class PropEvaluator
+    def initialize(action)
+      @action = action
+    end
+
+    def evaluate(props)
+      case props
+      when Hash
+        props.transform_values { |value| evaluate(value) }
+      when Props::Base
+        props.with(block: resolved_block(props.block))
+      when Proc
+        evaluate(@action.instance_exec(&props))
+      else
+        props
+      end
+    end
+
+    private
+
+    def resolved_block(block)
+      value = evaluate(@action.instance_exec(&block))
+      -> { value }
+    end
+  end
+end

data/lib/inertia_hanami/props.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module InertiaHanami
+  # Prop wrapper classes controlling how individual props are resolved and
+  # included in the Inertia response (partial reloads, deferred loading, etc).
+  module Props
+    # Base class for all prop wrappers. Built on Ruby's `Data`, so wrappers are
+    # immutable value objects with structural equality and no ActiveSupport
+    # dependency.
+    class Base < Data
+      def resolve
+        block.call
+      end
+    end
+
+    # A prop that is only included in the response when explicitly requested
+    # by the client (via a partial reload).
+    Optional = Base.define(:block)
+
+    # A prop that is always included in the response, even during a partial
+    # reload that would otherwise exclude it.
+    Always = Base.define(:block)
+
+    # A prop that is loaded in a subsequent request after the initial page
+    # load, batched together by `group`.
+    Defer = Base.define(:group, :block) do
+      def initialize(block:, group: "default")
+        super
+      end
+    end
+
+    # A prop that is evaluated only once and cached by the client.
+    Once = Base.define(:key, :fresh, :expires_in, :block) do
+      def initialize(block:, key: nil, fresh: false, expires_in: nil)
+        super
+      end
+
+      # Calculates the expiration timestamp in milliseconds.
+      #
+      # @return [Integer, nil] the expiration time as a Unix timestamp in milliseconds, or nil if no expiration
+      def expires_at
+        return unless expires_in
+
+        ((Time.now + expires_in).to_f * 1_000).to_i
+      end
+    end
+
+    # A prop whose value is merged with the existing client-side prop of the
+    # same name, instead of replacing it outright.
+    Merge = Base.define(:block, :deep_merge, :match_on) do
+      def initialize(block:, deep_merge: false, match_on: nil)
+        super
+      end
+    end
+
+    # A prop driving the client's infinite-scroll feature: merged (appended
+    # or prepended, per the X-Inertia-Infinite-Scroll-Merge-Intent header)
+    # instead of replacing the existing client-side prop, with pagination
+    # metadata surfaced via the response's `scrollProps` map.
+    Scroll = Base.define(:block, :match_on, :page_name, :previous_page, :next_page, :current_page) do
+      # rubocop:disable Metrics/ParameterLists -- one kwarg per client-visible scrollProps field
+      def initialize(block:, match_on: nil, page_name: "page", previous_page: nil, next_page: nil, current_page: nil)
+        super
+      end
+      # rubocop:enable Metrics/ParameterLists
+    end
+  end
+end