RubyGems - sinatra-inertia - Versions diffs - 0.1.0 - Mend

sinatra-inertia 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

checksums.yaml +7 -0
data/CHANGELOG.md +18 -0
data/LICENSE +21 -0
data/README.md +155 -0
data/lib/sinatra/inertia/async_sources.rb +18 -0
data/lib/sinatra/inertia/csrf_middleware.rb +125 -0
data/lib/sinatra/inertia/deferred.rb +82 -0
data/lib/sinatra/inertia/errors.rb +8 -0
data/lib/sinatra/inertia/helpers.rb +169 -0
data/lib/sinatra/inertia/middleware.rb +83 -0
data/lib/sinatra/inertia/response.rb +178 -0
data/lib/sinatra/inertia/version.rb +7 -0
data/lib/sinatra/inertia.rb +75 -0
metadata +102 -0

checksums.yaml ADDED Viewed

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 13a2feafd6c4d938912eed9edfe3b73df0b9fc5cabc0039de38a50c7ed7825cf
+  data.tar.gz: c15cf28f5b42b1babc98c0050a58abc81d26e1bc8b75fe1ca9cd7acf91573bb4
+SHA512:
+  metadata.gz: 22916e50a36a6f900a2cc8d100952596fa46c0ae1c191a1a129c286237bdae9b471ab2749955826300089eb3920b554aa2747cd5808c8cbc24a50923eabdfd83
+  data.tar.gz: a18a57fd4e7e2e8a1ccae01ad80fd3b73c7a1779d236b22b7e4265bf4240d16daa93ee7ff37a7590eca304b9fc81b5ed6675a3700f6efce24916fc2d7317c86e

data/CHANGELOG.md ADDED Viewed

@@ -0,0 +1,18 @@
+# Changelog
+## 0.1.0 — 2026-04-29
+* Initial release.
+* Full Inertia.js v2 wire protocol: page-object responses, version
+  mismatch (409 + X-Inertia-Location), partial reloads
+  (X-Inertia-Partial-{Component,Data,Except}), 303 redirect promotion.
+* Prop wrappers: `Inertia.always`, `Inertia.defer(group:)`,
+  `Inertia.optional` (alias `Inertia.lazy`), `Inertia.merge`,
+  `Inertia.once`.
+* Class-level DSL: `set :inertia_version`, `set :inertia_layout`,
+  `set :inertia_encrypt_history`, `inertia_share do … end`.
+* Per-request helpers: `inertia(component, props:)`, `render(inertia:)`
+  alias, `inertia_request?`, `inertia_errors`, `inertia_clear_history!`,
+  `inertia_encrypt_history!`.
+* Auto session sweep of validation errors on render.
+* Pure Sinatra dependency (no Rails, no homura coupling).

data/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 Kazuhiro Homma
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md ADDED Viewed

@@ -0,0 +1,155 @@
+# sinatra-inertia
+A Sinatra extension that implements the full **Inertia.js v2** wire protocol —
+page-object responses, version-mismatch detection, partial reloads,
+deferred / lazy / always / optional / merge / once props, encrypted history,
+303 redirect promotion, and error/flash session sweeps.
+Pure Sinatra-compatible: depends only on `sinatra` and `rack`. Runs on
+MRI Ruby and on the [homura](https://github.com/kazuph/homura) Cloudflare
+Workers + Opal stack.
+## Why "驚き最小"?
+Two principles drove the API:
+1. **Sinatra慣習に乗る.** Rendering a page is `inertia 'Component', props: {...}` —
+   the same shape as Sinatra's `erb :index`. A `render inertia: 'Component'`
+   alias is also provided for Rails refugees.
+2. **Class-level config uses `set` and `inertia_share do ... end`,**
+   matching Sinatra's existing DSL surface (`set :views`, `helpers do … end`).
+## Installation
+```ruby
+# Gemfile
+gem 'sinatra'
+gem 'sinatra-inertia'
+```
+## Hello, Inertia
+```ruby
+require 'sinatra'
+require 'sinatra/inertia'
+set :inertia_version, -> { ENV.fetch('ASSETS_VERSION', '1') }
+get '/' do
+  inertia 'Pages/Hello', props: { name: 'world' }
+end
+```
+```erb
+<!-- views/layout.erb -->
+<!doctype html>
+<html>
+<head>
+  <title>App</title>
+  <link rel="stylesheet" href="/assets/app.css">
+</head>
+<body>
+  <div id="app" data-page="<%= @page_json %>"></div>
+  <script type="module" src="/assets/app.js"></script>
+</body>
+</html>
+```
+## Public API
+### Helpers (per-request)
+| helper | purpose |
+|---|---|
+| `inertia(component, props:, layout:)` | Render an Inertia response (HTML on first hit, JSON on Inertia visit). |
+| `render(inertia: 'Comp', props: {...})` | Rails-style alias for the above. |
+| `inertia_request?` | True when `X-Inertia: true` header is present. |
+| `inertia_errors(payload = nil)` | Read or write validation errors that survive one redirect. |
+| `inertia_clear_history!` | Mark the next response's history as cleared. |
+| `inertia_encrypt_history!` | Mark the next response's history as encrypted. |
+### Class-level DSL
+| DSL | purpose |
+|---|---|
+| `set :inertia_version, -> { ... }` | Asset version. Mismatch on Inertia GET → 409 + `X-Inertia-Location`. |
+| `set :inertia_layout, :layout` | ERB layout used for full-page rendering (default `:layout`). |
+| `set :inertia_encrypt_history, true` | Default `encryptHistory: true` on every page. |
+| `inertia_share do … end` | Block whose return Hash is merged into every page's props. |
+### Prop wrappers (Inertia v2 transport modes)
+```ruby
+inertia 'Page', props: {
+  todos:  -> { Todo.all },                        # plain lazy
+  csrf:   Inertia.always { csrf_token },          # always sent
+  stats:  Inertia.defer(group: 'meta') { stats }, # excluded from initial response
+  filter: Inertia.optional { params[:f] },        # only on partial-reload request
+  feed:   Inertia.merge(page_items)               # client-side array merge
+}
+```
+| wrapper | semantics |
+|---|---|
+| bare `Proc`/`->` | resolved every request when included; partial-reload aware. |
+| `Inertia.always { … }` | always included, even on partials that omit it. |
+| `Inertia.defer(group:) { … }` | excluded on initial visit; client refetches in second roundtrip. |
+| `Inertia.optional { … }` | only resolved when explicitly requested via `X-Inertia-Partial-Data`. |
+| `Inertia.lazy { … }` | alias of `optional` (Inertia v1 name). |
+| `Inertia.merge(value)` | sent as a merge prop (`mergeProps` array on page object). Honours `X-Inertia-Reset: prop1,prop2` (Inertia 2.0) — reset props are emitted as plain values and dropped from `mergeProps`. |
+## Protocol features
+* **Initial GET** — full HTML response. The layout sees `@page_json` (HTML-
+  escaped JSON) and `@page` (raw Hash).
+* **Inertia visit** — `X-Inertia: true` request gets `Content-Type:
+  application/json`, `X-Inertia: true`, `Vary: X-Inertia`, body = page object.
+* **Version mismatch** — Inertia GET with mismatched `X-Inertia-Version` →
+  `409 Conflict` + `X-Inertia-Location: <url>`. Client hard-reloads.
+* **303 redirect promotion** — non-GET 302 responses are auto-promoted to
+  303 so the browser follows with GET.
+* **Partial reloads** — `X-Inertia-Partial-Component` + `X-Inertia-Partial-Data`
+  / `X-Inertia-Partial-Except` headers narrow which props are resolved.
+* **Encrypted history / clear history** — set per-app via setting or
+  per-route via `inertia_encrypt_history!` / `inertia_clear_history!`.
+* **Errors session** — `inertia_errors(field: 'msg')` survives one redirect
+  and is automatically swept on render.
+## Validation pattern (no 422, no client state)
+```ruby
+post '/todos' do
+  if params[:title].to_s.strip.empty?
+    inertia_errors title: "can't be blank"
+    redirect back  # 303 by middleware; Inertia client follows
+  else
+    Todo.create(params)
+    redirect '/', 303
+  end
+end
+get '/' do
+  inertia 'Todos/Index', props: {
+    todos: Todo.all,
+    values: { title: params[:title] }
+  }
+end
+```
+The error payload appears on the next render's `props.errors` and is
+swept from the session — exactly the experience described in the
+"modern monolith" articles, no 422 dance, no client state machine.
+## Compatibility
+* MRI Ruby ≥ 3.1
+* Sinatra ≥ 3.0 (incl. 4.x)
+* Rack ≥ 2.0 (incl. 3.x)
+* homura (Opal on Cloudflare Workers) — vendored Sinatra/Rack work as-is,
+  but **set `:logging, false`** in Workers builds because
+  `Rack::CommonLogger` uses `String#gsub!` (Opal does not implement
+  mutable string methods).
+## License
+MIT.

data/lib/sinatra/inertia/async_sources.rb ADDED Viewed

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+#
+# Registers `Sinatra::Inertia::Response`'s public methods as async sources
+# for the homura `auto-await` analyzer. When this gem is consumed inside a
+# homura Cloudflare Workers app, the analyzer sees `response.to_h` /
+# `response.to_json` calls and inserts `__await__` automatically — that's
+# how lazy/defer Procs returning JS Promises actually resolve before
+# JSON-serialization.
+#
+# Loaded only when the homura runtime is present (MRI / pure-Sinatra
+# environments don't need this; their `to_h` is fully synchronous).
+if defined?(::CloudflareWorkers) && defined?(::CloudflareWorkers::AsyncRegistry)
+  ::CloudflareWorkers::AsyncRegistry.register_async_source do
+    async_method 'Sinatra::Inertia::Response', :to_h
+    async_method 'Sinatra::Inertia::Response', :to_json
+  end
+end

data/lib/sinatra/inertia/csrf_middleware.rb ADDED Viewed

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+require 'securerandom'
+require 'rack/utils'
+module Sinatra
+  module Inertia
+    # Rack middleware implementing the Inertia / Laravel "double-submit
+    # cookie" CSRF pattern that `@inertiajs/react` and `@inertiajs/vue3`
+    # honour out of the box.
+    #
+    # Behaviour
+    # ---------
+    # * On every request, ensure a token cookie named `XSRF-TOKEN` is
+    #   present (generate + set on the response if missing).
+    # * For non-safe methods (POST / PUT / PATCH / DELETE), require the
+    #   request to send `X-XSRF-TOKEN` whose value matches the cookie.
+    #   Mismatch → `403 Forbidden`.
+    # * The cookie is *not* HttpOnly — Inertia's client reads it from
+    #   `document.cookie` and forwards it as `X-XSRF-TOKEN` automatically.
+    #
+    # Caveats
+    # -------
+    # Double-submit cookie is the standard Inertia/Laravel pattern but is
+    # weaker than synchronizer-token CSRF when an attacker has any
+    # script-injection foothold. Pair with:
+    #   * `SameSite=Lax` (default below) — the cookie won't ride
+    #     cross-site form posts.
+    #   * Strict CSP / no XSS.
+    #   * Optionally, server-side session-bound tokens via
+    #     `Rack::Protection::AuthenticityToken` instead.
+    #
+    # Configuration
+    # -------------
+    # `set :inertia_csrf_protection, false` disables this middleware. Use
+    # this only when the consumer ships its own CSRF defence. Safer
+    # defaults assume the gem is responsible.
+    class CSRFMiddleware
+      COOKIE_NAME = 'XSRF-TOKEN'
+      HEADER_KEY = 'HTTP_X_XSRF_TOKEN'
+      ENV_TOKEN_KEY = 'sinatra.inertia.csrf_token'
+      SAFE_METHODS = %w[GET HEAD OPTIONS].freeze
+      def initialize(app, same_site: :Lax)
+        @app = app
+        @same_site = same_site
+      end
+      def call(env)
+        existing = read_cookie(env)
+        token = existing || SecureRandom.urlsafe_base64(32)
+        env[ENV_TOKEN_KEY] = token
+        unless safe_method?(env)
+          header = env[HEADER_KEY].to_s
+          if existing.nil? || header.empty? || !secure_compare(header, existing)
+            return forbidden('CSRF token mismatch (expected matching X-XSRF-TOKEN header to XSRF-TOKEN cookie)')
+          end
+        end
+        status, headers, body = @app.call(env)
+        unless existing == token
+          set_cookie!(headers, token)
+        end
+        [status, headers, body]
+      end
+      private
+      def safe_method?(env)
+        SAFE_METHODS.include?(env['REQUEST_METHOD'])
+      end
+      def read_cookie(env)
+        cookie_header = env['HTTP_COOKIE'].to_s
+        return nil if cookie_header.empty?
+        cookie_header.split(/;\s*/).each do |pair|
+          name, value = pair.split('=', 2)
+          next unless name == COOKIE_NAME
+          return value
+        end
+        nil
+      end
+      def secure_compare(a, b)
+        # Constant-time compare. Avoid Rack::Utils.secure_compare here:
+        # the upstream implementation calls
+        # `OpenSSL.fixed_length_secure_compare` first, and on the homura
+        # Opal-on-Workers build that path either raises or silently
+        # diverges. Pure-Ruby compare keeps behaviour identical between
+        # MRI and Opal.
+        a = a.to_s
+        b = b.to_s
+        return false if a.bytesize != b.bytesize
+        diff = 0
+        a.bytes.zip(b.bytes) { |ai, bi| diff |= ai ^ bi }
+        diff.zero?
+      end
+      def set_cookie!(headers, token)
+        attrs = "#{COOKIE_NAME}=#{token}; Path=/; SameSite=#{@same_site}"
+        existing = headers['Set-Cookie']
+        # Normalise to a newline-joined String regardless of Rack 2/3
+        # conventions or downstream worker-runtime quirks. The Cloudflare
+        # Workers adapter that homura ships with serialises Array-shaped
+        # `Set-Cookie` headers as a literal JSON array, which breaks
+        # cookie parsing on the client.
+        prev = case existing
+               when nil, '' then nil
+               when Array then existing.join("\n")
+               else existing.to_s
+               end
+        headers['Set-Cookie'] = prev ? "#{prev}\n#{attrs}" : attrs
+      end
+      def forbidden(message)
+        body = "#{message}\n"
+        [403, {
+          'Content-Type' => 'text/plain; charset=utf-8',
+          'Content-Length' => body.bytesize.to_s
+        }, [body]]
+      end
+    end
+  end
+end

data/lib/sinatra/inertia/deferred.rb ADDED Viewed

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+module Sinatra
+  module Inertia
+    # Wrappers that mark props with Inertia v2 transport modes. They are
+    # plain value objects with a Proc payload; resolution happens inside
+    # PropsResolver (which knows whether the current request is a partial
+    # reload, what component it targets, what fields are requested, etc.).
+    #
+    # Usage:
+    #   inertia 'Page', props: {
+    #     todos:  -> { Todo.all },                # plain lazy: included by default, resolved on demand
+    #     stats:  Inertia.defer { compute_stats } # excluded from initial response, fetched in 2nd request
+    #     csrf:   Inertia.always { csrf_token }   # included even on partial reloads that omit it
+    #     filter: Inertia.optional { params[:f] } # only included when explicitly requested via partial
+    #     feed:   Inertia.merge(page_items)       # array merged with existing client-side feed
+    #     once:   Inertia.once { current_time }   # delivered exactly once; subsequent visits suppress
+    #   }
+    class Prop
+      attr_reader :block, :value, :group
+      def initialize(block: nil, value: nil, group: 'default')
+        @block = block
+        @value = value
+        @group = group
+      end
+      def resolve
+        block ? block.call : value
+      end
+      # Should this prop be included in *every* response (including partials
+      # that did not request it)?
+      def always? = false
+      # Is the value sent in the initial response, or deferred to a second
+      # roundtrip?
+      def deferred? = false
+      # Is this prop only included when explicitly requested via
+      # X-Inertia-Partial-Data?
+      def optional? = false
+      # Should arrays returned by this prop be merged with the client's
+      # existing array (Inertia 2 merge semantics)?
+      def merge? = false
+      # Once-only delivery (cleared from session/state after first emission).
+      def once? = false
+    end
+    class AlwaysProp < Prop
+      def always? = true
+    end
+    class DeferredProp < Prop
+      def deferred? = true
+    end
+    class OptionalProp < Prop
+      def optional? = true
+    end
+    class LazyProp < Prop
+      # `lazy` is the historical Inertia 1 alias of `optional`. Kept so
+      # existing code reads naturally.
+      def optional? = true
+    end
+    class MergeProp < Prop
+      def merge? = true
+    end
+    module_function
+    def always(value = nil, &block) = AlwaysProp.new(block: block, value: value)
+    def defer(group: 'default', &block) = DeferredProp.new(block: block, group: group)
+    def optional(&block) = OptionalProp.new(block: block)
+    def lazy(&block) = LazyProp.new(block: block)
+    def merge(value = nil, &block) = MergeProp.new(block: block, value: value)
+  end
+end

data/lib/sinatra/inertia/errors.rb ADDED Viewed

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+module Sinatra
+  module Inertia
+    Error = Class.new(StandardError)
+    InvalidProtocol = Class.new(Error)
+  end
+end

data/lib/sinatra/inertia/helpers.rb ADDED Viewed

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+require 'json'
+require_relative 'response'
+module Sinatra
+  module Inertia
+    # Sinatra helpers exposed to route handlers. Mounted by the
+    # `Sinatra::Inertia` extension.
+    module Helpers
+      # Render an Inertia response.
+      #
+      #   inertia 'Todos/Index', props: { todos: -> { Todo.all } }
+      #
+      # Layout selection: the configured layout (default `:layout`) is
+      # rendered for full HTML responses. The view receives `@page_json`
+      # (an HTML-escaped JSON string ready to drop into a `data-page`
+      # attribute) and `@page` (the underlying Hash, useful for SSR or
+      # custom rendering).
+      def inertia(component, props: {}, layout: nil)
+        layout = settings.respond_to?(:inertia_layout) ? settings.inertia_layout : :layout if layout.nil?
+        version = current_inertia_version
+        shared = current_inertia_shared
+        encrypt = if !@inertia_encrypt_history_override.nil?
+                    @inertia_encrypt_history_override == true
+                  elsif settings.respond_to?(:inertia_encrypt_history)
+                    settings.inertia_encrypt_history == true
+                  else
+                    false
+                  end
+        clear = @inertia_clear_history == true
+        # Read errors *before* sweeping so the response carries them, then
+        # sweep immediately so the next request sees a clean slate. The
+        # sweep must happen before any further session writes that the
+        # framework might serialise on commit.
+        errors_payload = inertia_errors_payload
+        sweep_inertia_session!
+        response_obj = Sinatra::Inertia::Response.new(
+          component: component,
+          props: props,
+          request: request,
+          version: version,
+          url: request.fullpath,
+          encrypt_history: encrypt,
+          clear_history: clear,
+          shared: shared,
+          errors: errors_payload
+        )
+        page_hash = response_obj.to_h
+        page_json = page_hash.to_json
+        if inertia_request?
+          content_type 'application/json; charset=utf-8'
+          headers['X-Inertia'] = 'true'
+          headers['Vary'] = 'X-Inertia'
+          return page_json
+        end
+        @page = page_hash
+        @page_json = ::Rack::Utils.escape_html(page_json)
+        erb layout, layout: false
+      end
+      # Rails-flavored alias: `render inertia: 'Component', props: {...}`
+      # We must preserve Sinatra's `render(engine, data = nil, options = {}, locals = {}, &block)`
+      # signature for the non-inertia path, so we forward *args/**kwargs.
+      def render(*args, **kwargs, &block)
+        first = args.first
+        if args.length == 1 && first.is_a?(Hash) && first.key?(:inertia)
+          inertia(first[:inertia], props: first[:props] || {}, layout: first[:layout])
+        elsif kwargs.key?(:inertia) && args.empty?
+          inertia(kwargs[:inertia], props: kwargs[:props] || {}, layout: kwargs[:layout])
+        else
+          super(*args, **kwargs, &block)
+        end
+      end
+      def inertia_request?
+        request.env['HTTP_X_INERTIA'] == 'true'
+      end
+      # CSRF token for the current request. Mounted by CSRFMiddleware
+      # (`set :inertia_csrf_protection, true` by default). Pair this with
+      # `inertia_share { { csrfToken: csrf_token } }` so the React/Vue
+      # client picks it up automatically — but note that when
+      # `Sinatra::Inertia::CSRFMiddleware` is active, the cookie + header
+      # exchange is already handled by the Inertia client; this helper is
+      # mainly for hidden-field forms or non-XHR submissions.
+      def csrf_token
+        request.env['sinatra.inertia.csrf_token']
+      end
+      # ------------------------------------------------------------------
+      # Shared props — runtime accessors (the `inertia_share` class DSL is
+      # in extension.rb, this is the per-request resolver).
+      def current_inertia_shared
+        blocks = settings.inertia_share_blocks || []
+        merged = {}
+        blocks.each do |b|
+          v = instance_exec(&b)
+          if v.is_a?(Hash)
+            merged = deep_merge(merged, v)
+          end
+        end
+        merged
+      end
+      # ------------------------------------------------------------------
+      # Asset version
+      def current_inertia_version
+        v = settings.respond_to?(:inertia_version) ? settings.inertia_version : nil
+        v.respond_to?(:call) ? v.call.to_s : v.to_s
+      end
+      # ------------------------------------------------------------------
+      # Errors / flash session sweep (per Inertia validation pattern).
+      # Consumers call `inertia_errors(field: 'message')` before redirecting
+      # to a form route; the next request renders the form with errors and
+      # sweeps them out of the session.
+      def inertia_errors(payload = nil)
+        if payload.nil?
+          (session[:_inertia_errors] || {}).dup
+        else
+          session[:_inertia_errors] = payload
+          payload
+        end
+      end
+      def inertia_clear_history!
+        @inertia_clear_history = true
+      end
+      def inertia_encrypt_history!(flag = true)
+        @inertia_encrypt_history_override = flag
+      end
+      def inertia_errors_payload
+        errors = session[:_inertia_errors]
+        return nil if errors.nil?
+        return nil if errors.respond_to?(:empty?) && errors.empty?
+        errors
+      end
+      def sweep_inertia_session!
+        # Rack::Session::Cookie tracks writes by hash mutation. On some
+        # session backends (e.g. the JSON-coder cookie store homura uses
+        # under Cloudflare Workers) `delete` is a no-op for the *backing
+        # cookie* — the change isn't serialised back. Force a write by
+        # assigning nil instead, which the JSON encoder still emits as
+        # `null` and makes `inertia_errors_payload` treat the field as
+        # absent on the next visit.
+        if session.respond_to?(:[]=)
+          session[:_inertia_errors] = nil
+        end
+      end
+      private
+      def deep_merge(a, b)
+        a.merge(b) do |_k, av, bv|
+          (av.is_a?(Hash) && bv.is_a?(Hash)) ? deep_merge(av, bv) : bv
+        end
+      end
+    end
+  end
+end

data/lib/sinatra/inertia/middleware.rb ADDED Viewed

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+module Sinatra
+  module Inertia
+    # Rack middleware handling concerns that must run *outside* the Sinatra
+    # request cycle:
+    #
+    #   * Version-mismatch detection. Per the Inertia protocol, an Inertia
+    #     GET visit whose `X-Inertia-Version` header disagrees with the
+    #     server's current asset version must be answered with
+    #     `409 Conflict` and a `X-Inertia-Location` header pointing at the
+    #     same URL — the client then performs a hard reload.
+    #
+    #   * Forced 303 redirects for non-GET requests. Inertia requires the
+    #     client follow the redirect with a GET, which only happens when the
+    #     server uses 303 See Other (the default 302 turns into a method-
+    #     preserving redirect on some browsers).
+    #
+    # The middleware is `register`-ed automatically by `Sinatra::Inertia`
+    # via `app.use`, so consumer apps don't need to wire it manually.
+    class Middleware
+      INERTIA_HEADER = 'HTTP_X_INERTIA'
+      INERTIA_VERSION_HEADER = 'HTTP_X_INERTIA_VERSION'
+      def initialize(app, version:)
+        @app = app
+        @version = version
+      end
+      def call(env)
+        if inertia_get?(env) && version_mismatch?(env)
+          location = env['REQUEST_URI'] || build_url(env)
+          return [
+            409,
+            { 'X-Inertia-Location' => location, 'Vary' => 'X-Inertia' },
+            []
+          ]
+        end
+        status, headers, body = @app.call(env)
+        # Promote 302 → 303 for Inertia non-GET visits so the client follows
+        # the redirect with a GET. Strictly limited to `X-Inertia: true`
+        # requests: a Sinatra app may serve plain REST endpoints alongside
+        # Inertia pages, and rewriting their 302s would silently change
+        # HTTP semantics for non-Inertia clients.
+        if status == 302 && env[INERTIA_HEADER] == 'true' &&
+           %w[POST PUT PATCH DELETE].include?(env['REQUEST_METHOD'])
+          status = 303
+        end
+        [status, headers, body]
+      end
+      private
+      def inertia_get?(env)
+        env[INERTIA_HEADER] == 'true' && env['REQUEST_METHOD'] == 'GET'
+      end
+      def version_mismatch?(env)
+        current = current_version
+        return false if current.nil? || current.empty?
+        env[INERTIA_VERSION_HEADER].to_s != current
+      end
+      def current_version
+        v = @version.respond_to?(:call) ? @version.call : @version
+        v.to_s
+      end
+      def build_url(env)
+        scheme = env['rack.url_scheme'] || 'http'
+        host = env['HTTP_HOST'] || env['SERVER_NAME']
+        path = env['PATH_INFO']
+        qs = env['QUERY_STRING']
+        full = +"#{scheme}://#{host}#{path}"
+        full << "?#{qs}" if qs && !qs.empty?
+        full
+      end
+    end
+  end
+end

data/lib/sinatra/inertia/response.rb ADDED Viewed

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+require_relative 'deferred'
+module Sinatra
+  module Inertia
+    # Builds the Inertia page object from a (component, props, request)
+    # tuple, applying partial-reload selection, deferred-prop excision,
+    # merge/once metadata, encrypted history flags, etc.
+    #
+    # The output is a Hash that gets serialized as JSON for X-Inertia
+    # responses, or interpolated into the layout's `data-page` attribute
+    # for full HTML responses.
+    class Response
+      attr_reader :component, :props, :request, :version, :url,
+                  :encrypt_history, :clear_history, :shared, :errors
+      def initialize(component:, props:, request:, version:, url: nil,
+                     encrypt_history: false, clear_history: false,
+                     shared: {}, errors: nil)
+        @component = component
+        @props = props || {}
+        @request = request
+        @version = version.to_s
+        @url = url || request.fullpath
+        @encrypt_history = encrypt_history
+        @clear_history = clear_history
+        @shared = shared || {}
+        @errors = errors
+      end
+      def to_h
+        merged_props = deep_merge(shared, props)
+        merged_props = merged_props.merge(errors: errors) if errors
+        partial = partial_request?
+        partial_data = partial_data_keys
+        partial_except = partial_except_keys
+        reset = reset_keys
+        resolved = {}
+        deferred_groups = {}
+        merge_keys = []
+        # NOTE: avoid block-based iteration here. On Opal, when this
+        # method runs as `async function` (because `await_if_promise`
+        # awaits a JS Promise), inner blocks like `Hash#each { ... }`
+        # do not natively suspend the outer function until the block
+        # body's awaits complete. A plain index-based loop preserves
+        # ordering and lets each iteration's `__await__` properly
+        # gate the next.
+        keys = merged_props.keys
+        i = 0
+        while i < keys.length
+          key = keys[i]
+          value = merged_props[key]
+          k = key.to_sym
+          included, materialized = decide(value, k, partial, partial_data, partial_except)
+          if included
+            resolved[k] = await_if_promise(materialized)
+            if value.is_a?(Prop) && value.merge? && !reset.include?(k)
+              merge_keys << k.to_s
+            end
+          elsif value.is_a?(Prop) && value.deferred?
+            (deferred_groups[value.group] ||= []) << k.to_s
+          end
+          i += 1
+        end
+        page = {
+          component: component,
+          props: resolved,
+          url: url,
+          version: version
+        }
+        page[:encryptHistory] = true if encrypt_history
+        page[:clearHistory] = true if clear_history
+        page[:deferredProps] = deferred_groups unless deferred_groups.empty?
+        page[:mergeProps] = merge_keys unless merge_keys.empty?
+        page
+      end
+      def to_json(*) = to_h.to_json
+      private
+      def partial_request?
+        request.env['HTTP_X_INERTIA_PARTIAL_COMPONENT'] == component
+      end
+      def partial_data_keys
+        raw = request.env['HTTP_X_INERTIA_PARTIAL_DATA'].to_s
+        return nil if raw.empty?
+        raw.split(',').map(&:strip).reject(&:empty?).map(&:to_sym)
+      end
+      def partial_except_keys
+        raw = request.env['HTTP_X_INERTIA_PARTIAL_EXCEPT'].to_s
+        return nil if raw.empty?
+        raw.split(',').map(&:strip).reject(&:empty?).map(&:to_sym)
+      end
+      # Inertia 2.0: `X-Inertia-Reset: a,b` tells the server "the client
+      # wants merge prop `a` and `b` to be replaced wholesale, not
+      # appended". We honour it by dropping the named keys from the
+      # outbound `mergeProps` array — the value itself is still resolved
+      # and emitted, so the client just doesn't accumulate it.
+      def reset_keys
+        raw = request.env['HTTP_X_INERTIA_RESET'].to_s
+        return [] if raw.empty?
+        raw.split(',').map(&:strip).reject(&:empty?).map(&:to_sym)
+      end
+      # Returns [included?, resolved_value]
+      def decide(value, key, partial, partial_data, partial_except)
+        if value.is_a?(Prop)
+          if value.always?
+            return [true, value.resolve]
+          elsif value.deferred?
+            return [false, nil] unless partial && partial_data&.include?(key)
+            return [true, value.resolve]
+          elsif value.optional?
+            return [false, nil] unless partial && partial_data&.include?(key)
+            return [true, value.resolve]
+          else
+            # merge / once / plain Prop
+            if partial
+              return [false, nil] if partial_data && !partial_data.include?(key)
+              return [false, nil] if partial_except&.include?(key)
+            end
+            return [true, value.resolve]
+          end
+        end
+        if value.is_a?(Proc)
+          # A bare Proc/Lambda is treated as plain lazy: resolved every
+          # request, but only when included.
+          if partial
+            return [false, nil] if partial_data && !partial_data.include?(key)
+            return [false, nil] if partial_except&.include?(key)
+          end
+          return [true, value.call]
+        end
+        # Plain value
+        if partial
+          return [false, nil] if partial_data && !partial_data.include?(key)
+          return [false, nil] if partial_except&.include?(key)
+        end
+        [true, value]
+      end
+      def deep_merge(a, b)
+        a.merge(b) do |_k, av, bv|
+          if av.is_a?(Hash) && bv.is_a?(Hash)
+            deep_merge(av, bv)
+          else
+            bv
+          end
+        end
+      end
+      # When running on the homura Cloudflare Workers / Opal runtime, a Proc
+      # may return a JS Promise (e.g. a sequel-d1 query result). The
+      # surrounding route handler is already an async function thanks to
+      # homura's auto-await analyzer, so we can resolve the Promise here
+      # via `.__await__`. On MRI this branch is dead code (no Cloudflare
+      # constant, no js_promise?), so plain Ruby tests are unaffected.
+      def await_if_promise(value)
+        if defined?(::Cloudflare) && ::Cloudflare.respond_to?(:js_promise?) && ::Cloudflare.js_promise?(value)
+          value.__await__
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/sinatra/inertia/version.rb ADDED Viewed

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+module Sinatra
+  module Inertia
+    VERSION = '0.1.0'
+  end
+end

data/lib/sinatra/inertia.rb ADDED Viewed

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+require 'sinatra/base'
+require_relative 'inertia/version'
+require_relative 'inertia/errors'
+require_relative 'inertia/deferred'
+require_relative 'inertia/response'
+require_relative 'inertia/middleware'
+require_relative 'inertia/csrf_middleware'
+require_relative 'inertia/helpers'
+require_relative 'inertia/async_sources'
+module Sinatra
+  # Inertia.js v2 protocol adapter for Sinatra.
+  #
+  #   class App < Sinatra::Base
+  #     register Sinatra::Inertia
+  #
+  #     set :inertia_version, -> { ASSETS_VERSION }
+  #     set :inertia_layout,  :layout
+  #
+  #     inertia_share do
+  #       { auth: { user: current_user }, flash: flash_payload }
+  #     end
+  #
+  #     get '/' do
+  #       inertia 'Todos/Index', props: { todos: -> { Todo.all } }
+  #     end
+  #   end
+  #
+  # See README.md for the full feature matrix.
+  module Inertia
+    def self.registered(app)
+      # Default settings — consumers override with `set :inertia_*` in app.
+      app.set :inertia_version, '1' unless app.respond_to?(:inertia_version)
+      app.set :inertia_layout,  :layout unless app.respond_to?(:inertia_layout)
+      app.set :inertia_encrypt_history, false unless app.respond_to?(:inertia_encrypt_history)
+      app.set :inertia_csrf_protection, true unless app.respond_to?(:inertia_csrf_protection)
+      app.set :inertia_share_blocks, []
+      # Mount CSRF middleware (double-submit XSRF-TOKEN cookie that
+      # @inertiajs/* clients honour). Opt-out via
+      # `set :inertia_csrf_protection, false` when the consumer ships
+      # its own (e.g. Rack::Protection::AuthenticityToken).
+      if app.settings.inertia_csrf_protection
+        app.use Sinatra::Inertia::CSRFMiddleware
+      end
+      # Mount protocol middleware (version mismatch + 303 redirect promotion).
+      app.use Sinatra::Inertia::Middleware, version: -> { app.settings.inertia_version }
+      # Class-level DSL: `inertia_share { ... }` registers a block whose
+      # return value is merged into every page's `props.shared` payload.
+      app.define_singleton_method(:inertia_share) do |&block|
+        raise ArgumentError, 'inertia_share requires a block' unless block
+        settings.inertia_share_blocks = settings.inertia_share_blocks + [block]
+      end
+      app.helpers Sinatra::Inertia::Helpers
+    end
+    # Convenience module-level constructors so code can write
+    #   Inertia.defer { compute }
+    # without `Sinatra::` prefix. Defined in deferred.rb.
+  end
+  register Inertia if respond_to?(:register)
+end
+# Top-level shortcut so consumers can write `Inertia.defer { ... }` without
+# prefixing every prop wrapper with `Sinatra::`. We deliberately do *not*
+# overwrite an existing `::Inertia` constant — if your app has one, use
+# `Sinatra::Inertia.defer` instead.
+::Inertia = Sinatra::Inertia unless defined?(::Inertia)

metadata ADDED Viewed

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: sinatra-inertia
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kazuhiro Homma
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sinatra
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: |
+  A Sinatra extension that implements the full Inertia.js v2 wire protocol:
+  page-object responses, version mismatch detection (409 + X-Inertia-Location),
+  partial reloads, deferred / lazy / always / optional / merge props,
+  encrypted history, redirect 303 handling, and error/flash session sweeps.
+  Pure Sinatra-compatible: depends only on `sinatra` and `rack`. Runs on MRI
+  Ruby and on the homura Cloudflare Workers + Opal stack.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/sinatra/inertia.rb
+- lib/sinatra/inertia/async_sources.rb
+- lib/sinatra/inertia/csrf_middleware.rb
+- lib/sinatra/inertia/deferred.rb
+- lib/sinatra/inertia/errors.rb
+- lib/sinatra/inertia/helpers.rb
+- lib/sinatra/inertia/middleware.rb
+- lib/sinatra/inertia/response.rb
+- lib/sinatra/inertia/version.rb
+homepage: https://github.com/kazuph/homura
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kazuph/homura
+  source_code_uri: https://github.com/kazuph/homura/tree/main/gems/sinatra-inertia
+  bug_tracker_uri: https://github.com/kazuph/homura/issues
+  changelog_uri: https://github.com/kazuph/homura/blob/main/gems/sinatra-inertia/CHANGELOG.md
+  readme_uri: https://github.com/kazuph/homura/blob/main/gems/sinatra-inertia/README.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Sinatra adapter for Inertia.js (v2 protocol)
+test_files: []