inertia-rage 0.0.1

data/lib/inertia/frontend.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "digest"
+require "net/http"
+
+module Inertia
+  ##
+  # Manages frontend asset integration for Inertia responses.
+  #
+  class Frontend
+    class << self
+      # Returns the root directory of the frontend application.
+      #
+      # Uses {Configuration#frontend_path} if set, otherwise searches for a
+      # Vite config file in common locations to determine where the frontend
+      # source lives.
+      #
+      # @return [Pathname] path to the frontend root directory
+      # @raise [RuntimeError] if no Vite config file is found
+      def root
+        @root ||= Inertia.config.frontend_path || begin
+          vite_config = Rage.root.glob(["*/vite.config.{js,ts,mjs,mts}", "app/*/vite.config.{js,ts,mjs,mts}"]).first
+          raise "Vite config not found" unless vite_config
+
+          vite_config.dirname
+        end
+      end
+
+      # Returns the directory containing built frontend assets.
+      #
+      # Uses {Configuration#build_path} if set, otherwise defaults to the
+      # `dist` directory inside the frontend root.
+      #
+      # @return [Pathname] path to the build output directory
+      # @raise [RuntimeError] if no Vite config file is found
+      def dist
+        @dist ||= Inertia.config.build_path || root.join("dist")
+      end
+
+      # Returns a version identifier for the frontend assets.
+      #
+      # Computes an MD5 hash of the Vite manifest or index.html to detect
+      # when assets have changed, enabling Inertia's asset versioning.
+      #
+      # @return [String] MD5 hex digest of the manifest file
+      # @raise [RuntimeError] if no Vite config file is found
+      def version
+        @version ||= begin
+          manifest = dist.glob([".vite/manifest.json", "index.html"]).first
+          Digest::MD5.file(manifest.to_s).hexdigest if manifest
+        end
+      end
+
+      # Returns the command prefix for executing npm packages.
+      #
+      # Detects the package manager by checking for lock files and returns
+      # the appropriate command to run package binaries.
+      #
+      # @return [String] command prefix (e.g., "npx", "pnpm exec", "yarn")
+      # @raise [RuntimeError] if no supported package manager is detected
+      def package_runner
+        @package_runner ||= if root.join("package-lock.json").exist?
+          "npx"
+        elsif root.join("pnpm-lock.yaml").exist?
+          "pnpm exec"
+        elsif root.join("bun.lockb").exist? || root.join("bun.lock").exist?
+          "bun x --bun"
+        elsif root.join("yarn.lock").exist?
+          "yarn"
+        elsif root.join("deno.lock").exist?
+          "deno x"
+        else
+          raise "No supported package manager detected"
+        end
+
+        @package_runner
+      end
+
+      # Renders the HTML layout with the Inertia page object embedded.
+      #
+      # In development, it fetches the layout from the Vite dev server and
+      # rewrites relative asset paths to absolute URLs. In production, it
+      # reads the pre-built layout from disk and caches it.
+      #
+      # @param data [Hash] the Inertia page object to embed
+      # @return [String] HTML document with page data injected
+      def render_layout(data)
+        if Rage.env.development?
+          build_dynamic_layout(data)
+        else
+          build_static_layout(data)
+        end
+      end
+
+      private
+
+      # Fetches the layout from Vite dev server and rewrites asset URLs.
+      #
+      # Transforms relative paths in src/href attributes and ES module imports
+      # to point to the Vite dev server.
+      #
+      # @param data [Hash] the Inertia page object to embed
+      # @return [String] HTML with rewritten URLs and page data
+      def build_dynamic_layout(data)
+        config = Inertia.config.dev_server
+        dev_server_url = "http://#{config.host}:#{config.port}"
+
+        retries = 0
+        begin
+          layout = Net::HTTP.get(URI(dev_server_url))
+        rescue Errno::ECONNREFUSED, Errno::EBADF
+          raise if (retries += 1) > 5
+          sleep 0.2
+          retry
+        end
+
+        layout.gsub!(/(src|href)=(["'])\/([^"']+)\2/) do
+          "#{$1}=\"#{dev_server_url}/#{$3}\""
+        end
+
+        layout.gsub!(/from\s*(["'])\/([^"']+)\1/) do
+          "from \"#{dev_server_url}/#{$2}\""
+        end
+
+        inject_page_data(layout, data)
+      end
+
+      # Returns the cached static layout with page data.
+      #
+      # @param data [Hash] the Inertia page object to embed
+      # @return [String] HTML with page data injected
+      # @raise [RuntimeError] if index.html does not exist in build path
+      def build_static_layout(data)
+        @layout ||= begin
+          layout = dist.join("index.html")
+          raise "Production layout not found at #{layout}. Ensure the frontend has been built" unless layout.exist?
+          layout.read
+        end
+
+        inject_page_data(@layout, data)
+      end
+
+      # Injects the page object JSON into the HTML body.
+      #
+      # @param layout [String] the HTML layout template
+      # @param data [Hash] the Inertia page object
+      # @return [String] HTML with page data script tag inserted after <body>
+      def inject_page_data(layout, data)
+        json_data = data.to_json
+        json_data.gsub!("<", '\u003c') if json_data.include?("<")
+
+        layout.sub(/<body([^>]*)>/i) do |body_tag|
+          <<~HTML
+            #{body_tag}
+              <script data-page="app" type="application/json">#{json_data}</script>
+          HTML
+        end
+      end
+    end
+  end
+end

data/lib/inertia/inertia.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "rage"
+
+require_relative "props"
+require_relative "frontend"
+require_relative "renderer"
+require_relative "request_context"
+require_relative "protocol_builder"
+require_relative "controller_helpers"
+require_relative "configuration"
+require_relative "middleware/version"
+require_relative "middleware/assets"
+require_relative "rage_extension"
+require_relative "version"
+
+module Inertia
+  # Configures the Inertia integration using a block.
+  #
+  # The block is evaluated in the context of the {Configuration} instance,
+  # allowing direct access to configuration setters.
+  #
+  # @yield Evaluates the block in the configuration context
+  # @example
+  #   Inertia.configure do |config|
+  #     config.frontend_path = "client"
+  #     config.build_on_start = false
+  #
+  #     config.dev_server.host = "0.0.0.0"
+  #     config.dev_server.port = 3000
+  #   end
+  def self.configure
+    yield config
+  end
+
+  # Returns the global configuration instance.
+  #
+  # @return [Configuration] the configuration object
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  # @!group Props
+  # Creates a deferred prop that will be loaded in a subsequent request after the initial page load.
+  #
+  # @param group [String] the group name for batching deferred props together
+  # @yield the block that returns the prop value when evaluated
+  # @return [Props::Deferred] a deferred prop wrapper
+  # @example
+  #   render inertia: "Users/Index", props: {
+  #     users: Inertia.deferred { User.all }
+  #   }
+  def self.deferred(group: "default", &block)
+    Props::Deferred.new(group:, block:)
+  end
+
+  # Creates a prop that is evaluated only once and cached by the frontend.
+  #
+  # @param key [String, nil] a unique cache key for the prop (auto-generated if `nil`)
+  # @param fresh [Boolean] forces re-evaluation when `true`
+  # @param expires_in [Integer, ActiveSupport::Duration, nil] cache expiration time in seconds
+  # @yield the block that returns the prop value when evaluated
+  # @return [Props::Once] a once-evaluated prop wrapper
+  # @example
+  #   render inertia: "Dashboard", props: {
+  #     stats: Inertia.once(expires_in: 300) { Stats.calculate }
+  #   }
+  def self.once(key: nil, fresh: false, expires_in: nil, &block)
+    Props::Once.new(key:, fresh:, expires_in:, block:)
+  end
+
+  # Creates a prop that is only included when explicitly requested by the client.
+  #
+  # @yield the block that returns the prop value when evaluated
+  # @return [Props::Optional] an optional prop wrapper
+  # @example
+  #   render inertia: "Users/Show", props: {
+  #     user: user,
+  #     permissions: Inertia.optional { user.permissions }
+  #   }
+  def self.optional(&block)
+    Props::Optional.new(block:)
+  end
+  # @!endgroup
+
+  autoload :ViteDevServer, "inertia/vite_dev_server"
+end

data/lib/inertia/middleware/assets.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Inertia
+  module Middleware
+    ##
+    # Serves built Vite assets in production using `x-sendfile` headers.
+    #
+    class Assets
+      EMPTY_BODY = [].freeze
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        method = env["REQUEST_METHOD"]
+        return @app.call(env) unless method == "GET" || method == "HEAD"
+
+        raw_path = env["PATH_INFO"]
+        return @app.call(env) unless raw_path.start_with?("/assets/")
+
+        [
+          200,
+          {
+            "x-sendfile" => raw_path.delete_prefix("/assets"),
+            "x-sendfile-root" => assets_root,
+            "cache-control" => "public, max-age=31536000, immutable"
+          },
+          EMPTY_BODY
+        ]
+      end
+
+      private
+
+      def assets_root
+        @assets_root ||= Frontend.dist.join("assets").realpath.to_s
+      end
+    end
+  end
+end

data/lib/inertia/middleware/version.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Inertia
+  module Middleware
+    ##
+    # Rack middleware that enforces Inertia asset version consistency.
+    #
+    # For GET requests carrying `X-Inertia-Version`, compares the client version
+    # with {Frontend.version}. A mismatch returns `409` with `X-Inertia-Location`,
+    # prompting the client to reload the current URL with the latest assets.
+    #
+    class Version
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        return @app.call(env) unless env["REQUEST_METHOD"] == "GET"
+
+        client_version = env["HTTP_X_INERTIA_VERSION"]
+
+        if client_version.nil? || client_version == server_version
+          @app.call(env)
+        else
+          [409, { "x-inertia-location" => Rack::Request.new(env).url }, []]
+        end
+      end
+
+      private
+
+      def server_version
+        @server_version ||= Frontend.version
+      end
+    end
+  end
+end

data/lib/inertia/props.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Inertia
+  # Contains prop wrapper classes.
+  module Props
+    # Base class for all prop wrappers.
+    class Base < Data
+      def resolve
+        block.call
+      end
+    end
+
+    # A prop that is loaded in a subsequent request after the initial page load.
+    Deferred = Base.define(:group, :block)
+
+    # A prop that is evaluated only once.
+    Once = Base.define(:key, :fresh, :expires_in, :block) do
+      # Calculates the expiration timestamp in milliseconds.
+      #
+      # @return [Integer, nil] the expiration time as 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 that is only included in the response when explicitly requested by the client.
+    Optional = Base.define(:block)
+  end
+end

data/lib/inertia/protocol_builder.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module Inertia
+  ##
+  # Builds the Inertia page object for a rendered component.
+  #
+  # ProtocolBuilder resolves the server-side props hash into the shape expected
+  # by the Inertia protocol. It applies partial reload filtering, evaluates lazy
+  # values, walks nested hashes and arrays, and collects protocol metadata such
+  # as `deferredProps` and `onceProps`.
+  #
+  # Nested prop paths are tracked with dot notation, e.g. `auth.user.name`, so
+  # request headers can target either a top-level prop or a nested value.
+  #
+  class ProtocolBuilder
+    # Internal marker returned by resolver methods when a prop should be
+    # left out of the page object.
+    OMIT = Object.new
+    private_constant :OMIT
+
+    # Page props should contain an `errors` object that defaults to {}
+    EMPTY_ERRORS = {}.freeze
+    private_constant :EMPTY_ERRORS
+
+    # Creates a new protocol builder.
+    #
+    # @param component [String] the Inertia component name being rendered
+    # @param props [Hash] the props provided by the controller
+    # @param context [RequestContext] request-specific partial reload context
+    def initialize(component, props, context:)
+      @props = props
+      @context = context
+
+      @response = { component:, url: context.url, version: Frontend.version }
+    end
+
+    # Builds the page object hash.
+    #
+    # @return [Hash] the Inertia page object payload
+    def call
+      props = resolve_props
+      props[:errors] = EMPTY_ERRORS unless props.has_key?(:errors)
+
+      @response[:props] = props
+      @response[:deferredProps] = @deferred_props_metadata if @deferred_props_metadata
+      @response[:onceProps] = @once_props_metadata if @once_props_metadata
+
+      @response
+    end
+
+    private
+
+    # Resolves a hash of props into protocol-ready response props.
+    #
+    # `parent_was_resolved` is set when traversing a hash or array returned by a
+    # lazy prop. In that case, the parent prop was already selected for this
+    # response, so partial reload `only` filtering should not prune children from
+    # the computed value.
+    #
+    # This flag does not mean every child was explicitly requested. Deferred and
+    # optional props inside the computed value are included on matching partial
+    # reloads, but remain deferred/omitted on initial loads. Once props still use
+    # their own path/key for cache exclusion, so resolving a parent does not by
+    # itself bypass `X-Inertia-Except-Once-Props`.
+    #
+    # @param props [Hash] props to resolve at the current nesting level
+    # @param path [String, nil] dot-notated path prefix for nested props
+    # @param parent_was_resolved [Boolean] whether this level came from a lazy prop
+    # @return [Hash] resolved props for this nesting level
+    def resolve_props(props = @props, path: nil, parent_was_resolved: false)
+      props.each_with_object({}) do |(prop_name, prop), response|
+        prop_name_with_path = prop_with_path(prop_name, path)
+
+        prop_status = @context.prop_status(prop_name_with_path)
+        next if prop_status == :excluded && !parent_was_resolved
+
+        is_explicitly_requested = (prop_status == :requested)
+        should_include_from_resolved_parent = parent_was_resolved && @context.partial_render?
+        should_include_on_demand_prop = is_explicitly_requested || should_include_from_resolved_parent
+
+        resolved = if prop.respond_to?(:call)
+          # lazy props
+          resolve_lazy_prop(prop, path: prop_name_with_path)
+
+        elsif prop.is_a?(Inertia::Props::Deferred)
+          if should_include_on_demand_prop
+            # the deferred prop was requested
+            prop.resolve
+          else
+            # let the client know there're deferred props
+            deferred_props_metadata[prop.group] << prop_name_with_path
+            OMIT
+          end
+
+        elsif prop.is_a?(Inertia::Props::Once)
+          key = prop.key || prop_name_with_path
+
+          # include metadata unless explicitly excluded (`parent_was_resolved` path)
+          once_props_metadata[key] = { prop: prop_name_with_path, expiresAt: prop.expires_at } unless prop_status == :excluded
+          # resolve the prop value only if requested
+          is_explicitly_requested || prop.fresh || !@context.once_prop_excluded?(key) ? prop.resolve : OMIT
+
+        elsif prop.is_a?(Inertia::Props::Optional)
+          # excluded on initial page load
+          should_include_on_demand_prop ? prop.resolve : OMIT
+
+        elsif prop.is_a?(Hash)
+          # nested hash props
+          if prop.empty?
+            prop
+          else
+            nested_prop = resolve_props(prop, path: prop_name_with_path, parent_was_resolved:)
+            nested_prop.empty? ? OMIT : nested_prop
+          end
+
+        elsif prop.is_a?(Array)
+          # nested array props
+          resolve_array_prop(prop, path: prop_name_with_path, parent_was_resolved:)
+
+        else
+          # scalar prop
+          prop
+        end
+
+        # chained props and props returned from lazy props
+        if resolved.is_a?(Inertia::Props::Base)
+          prop = resolved
+          redo
+        end
+
+        response[prop_name] = resolved unless resolved.equal?(OMIT)
+      end
+    end
+
+    # Evaluates a lazy prop and recursively resolves nested data it returns.
+    #
+    # A lazy prop can return a plain scalar value, a hash, or an array. Hashes and
+    # arrays are traversed with `parent_was_resolved: true` so nested
+    # optional/deferred props follow the resolved-parent rules described in `#resolve_props`.
+    #
+    # @param prop [#call] lazy value to evaluate
+    # @param path [String] dot-notated path of the lazy prop
+    # @return [Object] resolved value
+    def resolve_lazy_prop(prop, path:)
+      resolved = prop.call
+
+      if resolved.is_a?(Hash)
+        resolve_props(resolved, path:, parent_was_resolved: true)
+      elsif resolved.is_a?(Array)
+        resolve_array_prop(resolved, path:, parent_was_resolved: true)
+      else
+        resolved
+      end
+    end
+
+    # Resolves arrays that may contain nested hashes or lazy values.
+    #
+    # Array indices are included in generated paths so metadata can still point
+    # to the nested prop location, e.g. `items.0.author`.
+    #
+    # @param prop [Array] array value to resolve
+    # @param path [String] dot-notated path of the array prop
+    # @param parent_was_resolved [Boolean] whether the array came from a lazy prop
+    # @return [Array] resolved array
+    def resolve_array_prop(prop, path:, parent_was_resolved:)
+      prop.each_with_index.each_with_object([]) do |(nested_prop, i), response|
+        resolved = if nested_prop.is_a?(Hash)
+          resolve_props(nested_prop, path: "#{path}.#{i}", parent_was_resolved:)
+        elsif nested_prop.respond_to?(:call)
+          resolve_lazy_prop(nested_prop, path: "#{path}.#{i}")
+        else
+          nested_prop
+        end
+
+        # drop hash items whose contents were fully filtered out
+        next if nested_prop.is_a?(Hash) && !nested_prop.empty? && resolved.empty?
+
+        response << resolved
+      end
+    end
+
+    # Builds a dot-notated path for a prop at the current nesting level.
+    #
+    # @param prop_name [String, Symbol] prop key at the current level
+    # @param path [String, nil] parent path
+    # @return [String] full dot-notated prop path
+    def prop_with_path(prop_name, path)
+      if path
+        "#{path}.#{prop_name}"
+      else
+        prop_name.to_s
+      end
+    end
+
+    # Lazily initializes deferred prop metadata grouped by deferred group name.
+    #
+    # @return [Hash{String=>Array<String>}] deferred prop paths by group
+    def deferred_props_metadata
+      @deferred_props_metadata ||= Hash.new { |h, k| h[k] = [] }
+    end
+
+    # Lazily initializes once prop metadata keyed by once cache key.
+    #
+    # @return [Hash{String=>Hash}] once prop metadata
+    def once_props_metadata
+      @once_props_metadata ||= {}
+    end
+  end
+end

data/lib/inertia/rage_extension.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Inertia
+  ##
+  # Integrates the gem with Rage - the extension serves as the glue between Inertia
+  # and Rage, configuring rendering, asset handling, and controller helpers.
+  #
+  class RageExtension < Rage::Extension
+    configure do
+      # Register custom renderer to enable `render inertia: ...` syntax in controllers
+      config.renderer(:inertia) do |component, props: {}|
+        Renderer.call(component, props, controller: self)
+      end
+
+      # Automatically start Vite dev server in development mode
+      config.daemons << ViteDevServer if Rage.env.development?
+
+      # In production, serve prebuilt static assets via the public file server and Assets middleware
+      unless Rage.env.development?
+        config.public_file_server.enabled = true
+
+        config.middleware.allow_outside_request_fiber! do
+          config.middleware.insert_before 0, Middleware::Assets
+        end
+      end
+
+      # Enable automatic generation of `new` and `edit` routes via resource helpers
+      config.router.form_actions = true
+      # Verify asset version consistency between client and server
+      config.middleware.use Middleware::Version
+    end
+
+    # Include ControllerHelpers to add support for `redirect_to` and other Inertia-specific methods
+    initializer "inertia.rage.controller_helpers" do
+      RageController::API.include ControllerHelpers
+      RageController::API.extend ControllerHelpers::ClassMethods
+    end
+
+    # Prebuild frontend assets before launching the server in production
+    before_server_start do
+      if Inertia.config.build_on_start?
+        puts "INFO: Building frontend"
+        puts ""
+        system("#{Frontend.package_runner} vite build", chdir: Frontend.root) || abort("ERROR: Frontend build failed")
+      end
+    end
+  end
+end

data/lib/inertia/renderer.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Inertia
+  ##
+  # Renders Inertia responses from controller actions.
+  #
+  # This class enables the `render inertia:` DSL in controllers:
+  #
+  #   # Explicit component name
+  #   render inertia: "Users/Index", props: { users: User.all }
+  #
+  #   # Inferred component name
+  #   render inertia: { users: User.all } # => "UsersController#index" infers "Users/Index"
+  #
+  # For XHR requests with the `X-Inertia` header, returns a JSON response
+  # containing the Inertia page object. For standard requests, delegates to
+  # {Frontend.render_layout} to embed the page data in an HTML shell.
+  #
+  class Renderer
+    # Renders an Inertia response for the given component and props.
+    #
+    # This is the entry point for Inertia's custom rendering. It wires together
+    # {RequestContext} (partial reload filtering) and {ProtocolBuilder} (page object
+    # construction), and handles both XHR and initial page load responses.
+    #
+    # @param component [String, Hash] the Inertia component name, or props hash when using component name inference
+    # @param props [Hash] the props to pass to the component (ignored when `component` is a Hash)
+    # @param controller [RageController::API] the controller instance handling the request
+    # @return [String] JSON response for XHR requests, HTML for initial loads
+    def self.call(component, props, controller:)
+      request, headers = controller.request, controller.headers
+
+      unless component.is_a?(String)
+        raise ArgumentError, "props must be nil when using inferred component names" if props&.any?
+
+        props = component
+
+        component_path = controller.class.name.delete_suffix("Controller")
+        component_path.gsub!("::", "/")
+        action_name = controller.action_name
+        component_name = action_name.include?("_") ? action_name.split("_").map!(&:capitalize).join : action_name.capitalize
+
+        component = "#{component_path}/#{component_name}"
+      end
+
+      if shared_data = controller.inertia_shared_data
+        props = shared_data.merge(props)
+      end
+
+      context = RequestContext.new(request, component:)
+      data = ProtocolBuilder.new(component, props, context:).call
+
+      if headers["vary"]
+        headers["vary"] += ", x-inertia"
+      else
+        headers["vary"] = "x-inertia"
+      end
+
+      if request.env["HTTP_X_INERTIA"]
+        headers["x-inertia"] = "true"
+        headers["content-type"] = "application/json; charset=utf-8"
+        data.to_json
+      else
+        headers["content-type"] = "text/html; charset=utf-8"
+        Frontend.render_layout(data)
+      end
+    end
+  end
+end