inertia_rails_ssr_cache 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 71e26cafbbad0fef59528cf35fa5094b095a40b1488abfc0a229415e3cc697b0
+  data.tar.gz: a75e0b616adfad90ac03b1161c3a3a6173b8fbbaadba928a05a6439d017bcd18
+SHA512:
+  metadata.gz: b998c678608716c0dad23b2c52707569523b4b7c87f650ba5972c00add0d1337570c7f81a9587fda8191117d09056365bc82234d13f3013063f3fcfbef34f0a1
+  data.tar.gz: 72bfd354ae73778c477a42d87dae24df7c93a3b20738e383a32bef2a164be1819f6762ee24c3bfae65caa3351bf17f84d4508ef2c8de774dbbd43ebf7b31aad7

data/LICENSE.md

@@ -0,0 +1,319 @@
+# The Inertia Rails SSR Cache License
+
+The Inertia Rails SSR Cache License, version 1.0, an application of ShakaCode
+Trust-Based Commercial Licensing.
+
+Copyright (c) 2026 ShakaCode LLC, a Hawaii limited liability company
+("ShakaCode").
+
+SPDX-License-Identifier: LicenseRef-InertiaRailsSsrCache
+
+## Plain-language summary (informative, not part of the terms)
+
+Inertia Rails SSR Cache is trust-based: there is no license key, nothing
+phones home, and nothing in the software blocks, slows, or changes how
+your app runs based on license status. Reading the source, development,
+test, CI, staging, review apps, education, personal projects, and
+open-source work are free for everyone, at any organization size.
+Production use is also free if you can answer yes to all three
+questions: *Do fewer than 10 people work for your organization (counting
+all affiliates)? Was its revenue in the last twelve months under US $1M?
+Has it raised under US $1M in outside capital, ever?* Charities,
+educational institutions, and hospitals are free at any size. If any
+answer is no and you are none of those, production use requires a
+qualifying subscription: an active ShakaStack Pro subscription, which
+includes React on Rails Pro, covers organizations under 250 people and
+under US $10M revenue, and covers the whole organization: every
+application, environment, and developer. Larger organizations need a
+separate agreement. See https://pro.reactonrails.com/. Once a version
+ships under these terms, those terms govern that version permanently.
+
+## 1. Acceptance
+
+By using the software, you agree to these terms. If you use the software
+on behalf of an organization, you represent that you have authority to
+bind that organization, and "you" includes it.
+
+## 2. Definitions
+
+**"Software"** means Inertia Rails SSR Cache: the
+`inertia_rails_ssr_cache` Ruby gem, the `inertia-rails-ssr-cache` npm
+package, and any other component ShakaCode distributes under these terms.
+Inertia Rails, the Inertia.js adapters, and other dependencies that the
+software works with are licensed separately by their own authors.
+
+**"Control"** means ownership of more than 50% of the voting interests of
+an entity, or the power to direct its management or policies, by contract
+or otherwise.
+
+**"Your organization"** means you together with every entity that Controls
+you, that you Control, or that is under common Control with you. Teams,
+departments, and other sub-units are not separate organizations.
+
+**"Small Organization"** means an organization for which all of the
+following are true, counted across the entire organization as defined
+above:
+
+a. fewer than 10 individuals perform paid work for it or on its products
+   and services, whether directly or through staffing, outsourcing, or
+   services arrangements, counted as full-time equivalents;
+b. its total gross revenue, measured over the twelve months ending with
+   the most recently completed calendar quarter, was less than
+   US $1,000,000; and
+c. it has received less than US $1,000,000 in aggregate outside capital
+   over its lifetime (equity, tokens, convertible instruments, venture or
+   investor debt, accelerator funding, and grants or donations, other than
+   academic research or charitable grants to accredited academic or
+   nonprofit institutions) from sources other than its own operating
+   revenue and its founders' personal funds. Ordinary-course bank and
+   trade credit do not count.
+
+Government entities, other than public educational institutions, are not
+Small Organizations.
+
+**"Charity"** means an organization recognized as charitable or
+public-benefit under the law of the jurisdiction where it is organized (for
+example, a US 501(c)(3) organization or its equivalent elsewhere), no part
+of whose net earnings benefits any private person.
+
+**"Educational Institution"** means a school, college, university, or
+other institution whose principal purpose is teaching or academic
+research, whether public or private, including its libraries, research
+institutes, and teaching hospitals.
+
+**"Hospital"** means an institution licensed to provide inpatient
+medical care to the public, whether public, non-profit, or private,
+including its clinics and medical research units.
+
+Charity, Educational Institution, and Hospital status belongs to the
+qualifying entity and to affiliates that qualify on their own; it does
+not extend to for-profit affiliates, spin-offs, or commercial ventures
+that are not themselves one of these.
+
+**"Production use"** means running the software to serve an application,
+website, or service to its end users, whether those users are the public,
+your customers, or your own staff. Development, test, continuous
+integration, staging, preview, review-app, and other non-production
+environments are not production use.
+
+**"Subscription"** means an active paid subscription that ShakaCode
+designates as including the software: a ShakaStack Pro subscription
+(which includes React on Rails Pro) held by an organization that has
+fewer than 250 individuals counted as in clause (a) of the Small
+Organization definition and less than US $10,000,000 in total gross
+revenue measured as in clause (b), purchased at
+https://pro.reactonrails.com/ or through another order channel ShakaCode
+designates; or a separate written agreement with ShakaCode that covers
+the software. Any other organization needs such a separate written
+agreement. Sponsorships and donations that ShakaCode has not designated
+as subscriptions are appreciated but are not Subscriptions and grant no
+production-use rights.
+
+## 3. Copyright grant
+
+ShakaCode grants you a non-exclusive, worldwide, royalty-free license to
+use, copy, modify, and create derivative works of the software, and to
+include it in the builds and deployments of your organization's own
+applications, in each case only as allowed by these terms. You may share
+copies with contractors and service providers working on those
+applications, who must observe these terms. You may not distribute the
+software or your modifications as a standalone product or library, or as
+part of a product whose purpose is to provide the software's
+functionality to others (see Section 7).
+
+## 4. Free uses
+
+The following uses are free of charge for anyone, at any organization
+size:
+
+a. reading and studying the source code;
+b. development, test, continuous integration, staging, preview,
+   review-app, and every other non-production environment, without time
+   limit;
+c. evaluating the software in production for up to 45 days per
+   organization (not per version, person, or application), solely to
+   decide whether to adopt it;
+d. education and training of people, tutorials, demonstrations, and
+   academic research, in each case not directed at developing or
+   operating your organization's own products or services;
+e. personal and hobby projects;
+f. developing and operating a public open-source project distributed
+   under a license approved by the Open Source Initiative, where the
+   software runs as part of that project's own publicly available code
+   and primarily for that project's benefit, and not for the development
+   or operation of a proprietary product or service.
+
+In addition, **all production use is free of charge for a Small
+Organization, a Charity, an Educational Institution, or a Hospital, at
+any size for the last three.** If your organization is one of these,
+nothing in Section 5 applies to you.
+
+## 5. Paid uses
+
+Production use by an organization that is not a Small Organization, a
+Charity, an Educational Institution, or a Hospital requires a
+Subscription. This includes, without limitation, production use beyond
+the Section 4(c) evaluation window, internal applications used only by
+your staff, and applications you operate for your customers.
+
+In any conflict between Section 4 and this Section 5, use described in
+this Section 5 is production use and is not a free use under Section
+4(b), (c), or (d).
+
+**Client work.** If you use the software to build or run an application
+for a client, the use is attributed to the organization whose business
+the application ultimately serves, traced through any intermediaries.
+That organization's status determines whether the use is free or paid,
+and any required Subscription must be held by, or purchased for the
+benefit of and identifying, that organization. You may rely on a client's
+written self-certification of its status. A consulting firm's or agency's
+own applications are attributed to the firm or agency.
+
+## 6. Subscriptions
+
+One Subscription covers your whole organization: every application,
+environment, server, and developer of your organization, with no per-seat
+or per-application charge. A Subscription is governed by the subscription
+terms, order form, or other agreement under which it is purchased; if
+that agreement conflicts with these terms, that agreement controls. While
+a Subscription is active, ShakaCode provides software updates and
+reasonable support through its published channels; no response or
+resolution times are guaranteed unless an order or separate agreement
+says so. If a required Subscription expires or is terminated, your
+production use remains licensed for 30 days while you renew or wind down,
+and the software keeps running either way. ShakaCode and you may enter a
+separate written agreement that supplements or supersedes these terms.
+
+## 7. No hosted or embedded offering
+
+You may not provide the software or its cache-warming functionality to third
+parties as a hosted, managed, embedded, or bundled offering, for example
+a platform that builds or runs other organizations' Inertia Rails
+applications, without a separate written agreement with ShakaCode. Each
+organization whose applications use the software must independently
+qualify for free use or hold its own Subscription. Running your own
+applications for your own users, customers, or staff is not an offering
+to third parties.
+
+## 8. Trust, self-certification, and true-up
+
+These terms are enforced by trust, not technology: the software contains
+no license key, no activation, no usage telemetry, and no runtime
+lockout. You are responsible for determining in good faith whether your
+use is free or paid.
+
+If your organization stops qualifying as a Small Organization, your
+production use remains licensed for 60 days after the change; after that,
+continued production use requires a Subscription. No payment is owed for
+use during that window, and the obligation is not avoided by
+re-qualification within 12 months of the change.
+
+If you discover in good faith that past use required a Subscription,
+purchasing the applicable Subscription within 60 days of discovery is
+full compliance, and no back payment is owed for the good-faith period.
+If your organization made production use requiring a Subscription
+without a good-faith basis for treating it as free, ShakaCode may require
+payment of the applicable subscription fees for the period of that use,
+up to 24 months.
+
+You must not misrepresent your organization, its size or status, or your
+license status.
+
+## 9. Redistribution and notices
+
+Copies of the software and derivative works that these terms allow you to
+make must remain under these same terms and must retain these terms, all
+copyright and attribution notices, and the SPDX identifier.
+
+## 10. Patents
+
+ShakaCode grants you a license under any patent claims it can license that
+are necessarily infringed by the software, only for uses allowed by these
+terms. This patent license ends immediately if you or your organization
+initiate a patent claim (excluding counterclaims and cross-claims filed in
+response to a patent claim first brought against you) alleging that the
+software infringes a patent.
+
+## 11. Trademarks
+
+These terms grant no rights in the names, logos, or trademarks of
+ShakaCode or Inertia Rails SSR Cache, except for truthful factual
+references.
+
+## 12. Per-version terms, breach, and cure
+
+These terms apply per version: the terms delivered with a version of the
+software govern that version permanently, and patch and security releases
+of a version line remain under that line's terms. Later versions may be
+offered under different terms.
+
+If you breach these terms, your license ends automatically 30 days after
+ShakaCode provides written notice of the breach, unless you cure it within
+that period; upon cure, your license is reinstated retroactively. Curing
+continued production use during a lapsed Subscription includes payment of
+the applicable fees for the lapsed period.
+
+## 13. Feedback
+
+If you submit feedback, suggestions, or improvements to ShakaCode, you
+grant ShakaCode a worldwide, royalty-free, irrevocable license to use and
+incorporate them.
+
+## 14. Disclaimer and limitation of liability
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+PURPOSE, TITLE, AND NON-INFRINGEMENT. TO THE MAXIMUM EXTENT PERMITTED BY
+LAW, SHAKACODE WILL NOT BE LIABLE FOR ANY INDIRECT, SPECIAL, INCIDENTAL,
+OR CONSEQUENTIAL DAMAGES ARISING FROM OR RELATED TO THE SOFTWARE OR THESE
+TERMS, AND SHAKACODE'S TOTAL LIABILITY WILL NOT EXCEED THE AMOUNTS YOU
+PAID SHAKACODE FOR THE SOFTWARE IN THE TWELVE MONTHS BEFORE THE CLAIM
+AROSE.
+
+## 15. Assignment, governing law, and miscellaneous
+
+You may assign these terms, together with any active Subscription, to a
+successor in connection with a merger, acquisition, or sale of
+substantially all assets, upon notice to ShakaCode; these terms are
+otherwise non-transferable. These terms are governed by the laws of the
+State of Hawaii, USA, excluding its conflict-of-law rules, with exclusive
+jurisdiction and venue in the state and federal courts located in
+Honolulu, Hawaii. If a provision of these terms is unenforceable, the
+remainder stays in effect. These terms, together with any subscription
+agreement or order, are the entire agreement about the software; if they
+conflict, the order controls.
+
+## 16. Questions and commercial licensing
+
+contact@shakacode.com · https://pro.reactonrails.com/ ·
+https://github.com/shakacode/commercial-licensing
+
+## Machine-readable summary (informative)
+
+```yaml
+license_name: The Inertia Rails SSR Cache License 1.0
+spdx_identifier: LicenseRef-InertiaRailsSsrCache
+type: trust-based commercial
+free_production_use_if_all:
+  max_org_headcount_fte: 10        # exclusive; whole control group
+  max_ttm_revenue_usd: 1000000     # exclusive; trailing 12 months
+  max_lifetime_outside_capital_usd: 1000000  # exclusive
+free_production_use_if_any:
+  - charity                        # recognized charitable / public-benefit org, any size
+  - educational_institution        # school, college, university, any size
+  - hospital                       # licensed inpatient care provider, any size
+always_free: [read, study, development, test, ci, staging, preview, review_apps, evaluate_in_production_45_days, education, personal, oss_projects]
+paid: production use by any other organization; included in an active ShakaStack Pro subscription for organizations under 250 people and under USD 10M revenue; otherwise a separate written agreement
+license_key: none
+runtime_enforcement: none  # no activation, no telemetry, no lockout
+attribution_required: false
+subscription_lapse_grace_days: 30
+outgrow_free_line_grace_days: 60
+per_version_terms: true
+pricing_url: https://pro.reactonrails.com/
+contact: contact@shakacode.com
+```
+
+## Version history (informative)
+
+Version 1.0 is the first license under which the software is distributed.

data/README.md

@@ -0,0 +1,196 @@
+# Inertia Rails SSR Cache
+
+Warm the server-side rendering (SSR) cache of an Inertia Rails app after each
+deploy, so the first visitors to your public pages get cached SSR HTML instead of
+waiting for Node to render it.
+
+You list the public paths to warm. One Active Job job requests each path the way an
+anonymous visitor would and checks that a second, fresh request reuses the same
+cache entry Inertia wrote. Inertia keeps owning page serialization, cache keys and
+cache writes; this gem only drives and verifies them. A small npm companion,
+`guardRelease`, wraps your Node SSR callback so a page from one release is never
+rendered by another release's bundle.
+
+Version 0.1.0 is an early release. Run the
+[adopter pilot](docs/releasing.md#adopter-pilot-before-production-use) with your
+own routes, cache topology and load before enabling warming in production.
+
+Works with any Active Job backend; there is no Sidekiq requirement. GQL LRU warming
+is out of scope.
+
+## What is tested
+
+- Ruby 3.3+, Rails 7.2–8.1 and `inertia_rails` 3.22.x.
+- The Rails integration suite runs against Inertia React 3.9.1, including reuse
+  of a FileStore cache from a separate web process.
+- The `guardRelease` callback type is checked against the `createServer`
+  callbacks of Inertia React, Vue 3 and Svelte 3.9.1. A Node test renders a Vue 3
+  page through the guard. Svelte is checked for types only.
+- Node 22.18+; the npm package is ESM only.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "inertia_rails_ssr_cache", "~> 0.1.0"
+```
+
+```sh
+bundle install
+npm install inertia-rails-ssr-cache@0.1.0
+```
+
+Install the same version of both packages.
+
+## Application setup
+
+Configure Inertia normally. Use an immutable release token embedded in the SSR
+bundle and a retaining cache store shared by warming workers and web processes.
+Warming requires `config.enable_reloading = false` and
+`config.allow_concurrency` must not be `false`. Enqueueing and execution reject
+these unsupported settings: nested requests can deadlock against the surrounding
+job's Rails reload or concurrency locks.
+
+```ruby
+# config/initializers/inertia.rb
+InertiaRails.configure do |config|
+  config.ssr_enabled = true
+  config.ssr_cache = { expires_in: 1.hour }
+  config.version = ENV.fetch("APP_RELEASE")
+end
+
+# config/initializers/inertia_rails_ssr_cache.rb
+InertiaRailsSsrCache.configure do |config|
+  config.origin = "https://www.example.com"
+  config.paths = ["/", "/pricing", "/features"]
+  config.queue_name = :ssr_warming
+end
+```
+
+Wrap your existing Node SSR callback:
+
+```typescript
+import { guardRelease } from 'inertia-rails-ssr-cache';
+import createServer from '@inertiajs/react/server';
+
+// Replace with a literal or bundler-defined value embedded during the build.
+createServer(guardRelease('build-42', renderPage));
+```
+
+The embedded value must equal Rails' `APP_RELEASE`. A runtime environment value
+alone cannot identify which JavaScript was built. Deploy with a fresh version
+when first adding the guard; cache hits do not execute the callback, so it cannot
+certify old entries written by an unguarded renderer.
+
+After the candidate Rails workers, SSR service and database are ready:
+
+```ruby
+job_id = InertiaRailsSsrCache.warm_later
+```
+
+Or enqueue through the Rails task:
+
+```sh
+bin/rails inertia_rails_ssr_cache:warm
+```
+
+The returned job ID confirms enqueueing, not completion. Monitor normal Active
+Job failures and `target.inertia_rails_ssr_cache` / `warm.inertia_rails_ssr_cache`
+notifications. Target results report a reason such as `reused`,
+`missing_cache_evidence`, `cache_key_changed`, `cache_not_reused`, `http_failure`,
+`release_mismatch` or `invalid_ssr_value`. A failed run raises
+`InertiaRailsSsrCache::WarmFailed` with its report. Events contain target/result
+metadata, not page props or HTML.
+
+## What verification means
+
+Each job processes at most 50 distinct registered paths sequentially. Each path
+gets two fresh anonymous HTML GETs through the full Rails middleware stack,
+without credentials, cookie carry-over, Inertia visit headers or redirect
+following. The synthetic Rack environment uses source address `192.0.2.1` and no
+User-Agent header. Both responses must be HTTP 200 HTML. Each must produce exactly one
+native SSR cache-fetch observation, and the second must hit the first one's key.
+The retained entry must also contain a string body and an array of string head
+entries; cached null/false values do not qualify.
+
+This catches normal client-rendering fallback, disabled/nonretaining caches and
+unstable page data. Success describes observed reuse at that moment; eviction,
+expiry and future request variants can still cause misses. The application must
+approve safe public GETs and deterministic anonymous props that do not vary by
+client IP, geolocation or browser identity. Context-dependent
+Inertia versions are unsupported: worker and controller versions must agree.
+
+A native SSR hit avoids Node rendering. Controllers, queries and prop resolution
+still execute. This package makes no database-cache or production latency claim.
+
+## Operational limits
+
+- Concurrency is one request per job. Multiple jobs can overlap; configure a
+  dedicated queue's concurrency in your Active Job backend.
+- Each request uses a fresh joined thread to preserve the surrounding job's
+  Rails executor and CurrentAttributes. Allow for an additional database
+  connection if job callbacks retain one while waiting for the request.
+- Route count is bounded, but execution has no hard wall-clock deadline.
+  Inertia Rails 3.22 uses its HTTP client's timeouts. The warmer does not interrupt
+  Rails requests with asynchronous Ruby timeouts. If the host interrupts a job,
+  it waits for its active request to finish before unwinding; shutdown can be
+  delayed by the remaining request duration.
+- Readiness, migrations, replica lag, cutover and cancellation remain deployment
+  responsibilities. No scheduler, distributed lock or durable run registry is
+  installed. Retrying repeats eligible GETs and reuses entries already present.
+- Queued jobs carry their intended release and recheck it at execution. Rollbacks
+  use the matching guarded bundle and immutable Inertia version.
+- Worker and web cache topology must match. MemoryStore only warms one process;
+  the integration suite proves reuse with FileStore across separate processes.
+- Native cache instrumentation compatibility is intentionally limited to the
+  tested Inertia Rails 3.22 line. A future adapter upgrade needs contract tests.
+- Cache namespaces must be absent or static strings. Callable namespaces and
+  custom key encodings cannot be verified. FileStore support covers the built-in
+  class with keys that fit in one encoded filename. Longer keys and subclasses
+  are unsupported and can fail verification even if native caching works.
+
+## Development
+
+Ruby 3.3+, Rails 7.2–8.1, `inertia_rails` 3.22.x, Node 22.18+ and the pnpm version
+pinned in `package.json`. The Rails integration fixture and demo use Inertia React
+3.9.1. The npm guard is also type-checked against Inertia Vue 3 and Svelte 3.9.1,
+and renders a Vue 3 page in a Node test; Svelte has no runtime test.
+
+```sh
+bin/setup
+bin/validate
+bin/audit
+```
+
+`bin/validate` runs behavior, type, lint, workflow and package checks. `bin/audit`
+checks dependency advisories and requires network access. See the manifests and
+[contribution guide](CONTRIBUTING.md) for the exact tools and commands.
+
+## Runnable demo
+
+Run `bin/demo` after `bin/setup` to start a small Inertia Rails app with React
+SSR, a Solid Queue Active Job worker and a shared FileStore cache. Run
+`bin/demo verify` for an isolated proof that warming completes and a separate
+web process reuses the same native SSR entry. See the
+[demo guide](examples/demo/README.md) for commands, configuration and limits.
+
+See [architecture](docs/architecture.md), [source research](docs/grounding.md),
+[design comparison](docs/design-comparison.md), the [changelog](CHANGELOG.md) and
+the [release procedure](docs/releasing.md).
+
+## License
+
+Inertia Rails SSR Cache uses ShakaCode Trust-Based Commercial Licensing, under
+[The Inertia Rails SSR Cache License](LICENSE.md).
+
+TL;DR: development, test, CI, staging and preview use is free for
+everyone. Production use is free for organizations under 10 people, $1M
+revenue and $1M raised, and for charities, schools and hospitals at any
+size. Otherwise, an active ShakaStack Pro subscription (which includes
+React on Rails Pro) covers it for organizations under 250 people and
+$10M revenue; see [pro.reactonrails.com](https://pro.reactonrails.com/).
+Larger organizations and questions:
+[contact@shakacode.com](mailto:contact@shakacode.com).
+
+There are no license keys and nothing phones home. [LICENSE.md](LICENSE.md) is the
+binding text.

data/lib/inertia_rails_ssr_cache/configuration.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 ShakaCode LLC.
+#
+# SPDX-License-Identifier: LicenseRef-InertiaRailsSsrCache
+#
+# This file is part of Inertia Rails SSR Cache. Use is governed by The
+# Inertia Rails SSR Cache License in LICENSE.md.
+
+require "uri"
+
+module InertiaRailsSsrCache
+  class ConfigurationError < StandardError; end
+
+  # Boot-time registration is the only authority for eligible anonymous requests.
+  class Configuration
+    MAX_TARGETS = 50
+    RELEASE = /\A[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}\z/
+    INVALID_CHARACTERS = /[\\\x00-\x20\x7f]/
+
+    attr_accessor :origin, :paths, :queue_name
+
+    def initialize
+      @origin = nil
+      @paths = []
+      @queue_name = :ssr_warming
+    end
+
+    def validate!
+      @origin = self.class.validate_origin(origin).dup.freeze
+      @paths = self.class.validate_paths(paths)
+      @queue_name = self.class.validate_queue_name(queue_name)
+      freeze
+    end
+
+    def verify_targets!(requested_origin, requested_paths)
+      checked_origin = self.class.validate_origin(requested_origin)
+      checked_paths = self.class.validate_paths(requested_paths)
+      unless checked_origin == origin && checked_paths.all? { |path| paths.include?(path) }
+        raise ConfigurationError, "queued targets are no longer registered"
+      end
+
+      checked_paths
+    end
+
+    def self.validate_release(value)
+      unless value.is_a?(String) && RELEASE.match?(value)
+        raise ConfigurationError,
+              "release must be 1-128 ASCII letters, digits, dots, underscores or hyphens, starting alphanumeric"
+      end
+
+      value
+    end
+
+    def self.validate_queue_name(value)
+      unless (value.is_a?(String) || value.is_a?(Symbol)) && !value.to_s.strip.empty?
+        raise ConfigurationError, "queue_name must be a nonempty string or symbol"
+      end
+
+      value.to_s.dup.freeze
+    end
+
+    def self.valid_origin?(parsed)
+      parsed.is_a?(URI::HTTP) && !parsed.host.to_s.empty? && parsed.path == "" &&
+        [parsed.userinfo, parsed.query, parsed.fragment].all?(&:nil?)
+    end
+
+    def self.validate_origin(value)
+      unless value.is_a?(String) && !INVALID_CHARACTERS.match?(value)
+        raise ConfigurationError, "origin must be an absolute HTTP(S) origin"
+      end
+
+      parsed = URI.parse(value)
+      unless valid_origin?(parsed)
+        raise ConfigurationError, "origin must contain only HTTP(S) scheme and host, with an optional port"
+      end
+
+      value
+    rescue URI::InvalidURIError
+      raise ConfigurationError, "origin is not a valid URI"
+    end
+
+    def self.validate_paths(value)
+      unless value.is_a?(Array) && !value.empty? && value.all?(String)
+        raise ConfigurationError, "paths must be a nonempty array of rooted paths"
+      end
+
+      paths = value.uniq
+      if paths.size > MAX_TARGETS
+        raise ConfigurationError,
+              "at most #{MAX_TARGETS} distinct paths may be warmed per job"
+      end
+
+      paths.each { |path| validate_path(path) }
+      paths.map { |path| path.dup.freeze }.freeze
+    end
+
+    def self.validate_path(path)
+      unless path.start_with?("/") && !path.start_with?("//") && !INVALID_CHARACTERS.match?(path)
+        raise ConfigurationError, "each path must be rooted and must not contain an authority or control characters"
+      end
+
+      parsed = URI.parse(path)
+      unless [parsed.fragment, parsed.host, parsed.scheme].all?(&:nil?)
+        raise ConfigurationError, "paths must not contain fragments, hosts or schemes"
+      end
+    rescue URI::InvalidURIError
+      raise ConfigurationError, "path is not a valid URI"
+    end
+  end
+end

data/lib/inertia_rails_ssr_cache/probe.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 ShakaCode LLC.
+#
+# SPDX-License-Identifier: LicenseRef-InertiaRailsSsrCache
+#
+# This file is part of Inertia Rails SSR Cache. Use is governed by The
+# Inertia Rails SSR Cache License in LICENSE.md.
+
+require "rack/mock"
+require "active_support/dependencies"
+require "active_support/notifications"
+
+module InertiaRailsSsrCache
+  # The native-key format belongs only here; compatibility is pinned to Inertia Rails 3.22.
+  class Probe
+    Fetch = Data.define(:key, :native_key, :hit, :namespace, :version)
+    NATIVE_KEY = %r{\Ainertia_ssr/[0-9a-f]{32}\z}
+
+    def self.call(origin:, path:)
+      Thread.handle_interrupt(Object => :never) { wait_for_request(start_request(origin, path)) }
+    end
+
+    def self.start_request(origin, path)
+      Thread.new do
+        Thread.current.report_on_exception = false
+        Thread.handle_interrupt(Object => :immediate) { new(origin, path).call }
+      end
+    end
+
+    def self.wait_for_request(request_thread)
+      # Rails request middleware resets its executor; isolate it from the job's executor.
+      Thread.handle_interrupt(Object => :immediate) do
+        ActiveSupport::Dependencies.interlock.permit_concurrent_loads { request_thread.value }
+      end
+    ensure
+      drain_request(request_thread)
+    end
+
+    def self.drain_request(request_thread)
+      # Never interrupt Rails completion callbacks or replace an interrupted parent's error.
+      # The normal wait above already propagates request exceptions.
+      ActiveSupport::Dependencies.interlock.permit_concurrent_loads { request_thread.join }
+    rescue Exception # rubocop:disable Lint/RescueException
+      raise if request_thread.alive?
+    end
+    private_class_method :start_request, :wait_for_request, :drain_request
+
+    def initialize(origin, path)
+      @origin = origin
+      @path = path
+      @fetches = []
+      @owner_thread = Thread.current
+      @owner_fiber = Fiber.current
+    end
+
+    def call
+      response = ActiveSupport::Notifications.subscribed(method(:record), "cache_read.active_support") { request }
+      Observation.new(status: response.status, html: response.media_type == "text/html",
+                      fetches: @fetches.map { |fetch| [fetch.key, fetch.hit] }, ssr: retained_ssr?)
+    end
+
+    private
+
+    def request
+      Rack::MockRequest.new(Rails.application).get(
+        "#{@origin}#{@path}",
+        "HTTP_HOST" => @origin.sub(%r{\Ahttps?://}i, ""),
+        "HTTP_ACCEPT" => "text/html",
+        "REMOTE_ADDR" => "192.0.2.1"
+      )
+    end
+
+    def record(*)
+      return unless Thread.current.equal?(@owner_thread) && Fiber.current.equal?(@owner_fiber)
+
+      payload = ActiveSupport::Notifications::Event.new(*).payload
+      return unless payload[:super_operation] == :fetch
+
+      native_key = native_key(payload)
+      return unless native_key
+
+      @fetches << Fetch.new(payload[:key], native_key, payload[:hit] == true, payload[:namespace], payload[:version])
+    end
+
+    def native_key(payload)
+      logical_key = logical_key(payload[:key], payload[:store])
+      return unless logical_key
+
+      namespace = payload[:namespace]
+      return unless namespace.nil? || namespace.is_a?(String)
+
+      logical_key = logical_key.delete_prefix("#{namespace}:") if namespace
+      logical_key if NATIVE_KEY.match?(logical_key)
+    rescue Encoding::CompatibilityError
+      nil
+    end
+
+    def retained_ssr?
+      return false unless @fetches.size == 1
+
+      fetch = @fetches.fetch(0)
+      value = InertiaRails.cache_store.read(fetch.native_key, namespace: fetch.namespace, version: fetch.version)
+      Observation.ssr_value?(value)
+    end
+
+    def logical_key(key, store)
+      return unless key.is_a?(String)
+
+      decoded = if store == "ActiveSupport::Cache::FileStore"
+                  URI.decode_www_form_component(File.basename(key))
+                else
+                  key
+                end
+      decoded if decoded.valid_encoding?
+    rescue ArgumentError
+      # Unparseable notification keys must not interrupt unrelated cache requests.
+      nil
+    end
+  end
+end

data/lib/inertia_rails_ssr_cache/railtie.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 ShakaCode LLC.
+#
+# SPDX-License-Identifier: LicenseRef-InertiaRailsSsrCache
+#
+# This file is part of Inertia Rails SSR Cache. Use is governed by The
+# Inertia Rails SSR Cache License in LICENSE.md.
+
+module InertiaRailsSsrCache
+  class Railtie < Rails::Railtie
+    rake_tasks do
+      namespace :inertia_rails_ssr_cache do
+        desc "Enqueue native SSR cache warming for registered public routes"
+        task warm: :environment do
+          puts "Enqueued SSR warming job #{InertiaRailsSsrCache.warm_later}"
+        end
+      end
+    end
+  end
+end

data/lib/inertia_rails_ssr_cache/result.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 ShakaCode LLC.
+#
+# SPDX-License-Identifier: LicenseRef-InertiaRailsSsrCache
+#
+# This file is part of Inertia Rails SSR Cache. Use is governed by The
+# Inertia Rails SSR Cache License in LICENSE.md.
+
+module InertiaRailsSsrCache
+  # Evidence interpretation is pure; framework events are reduced before this boundary.
+  class Observation
+    attr_reader :status, :html, :fetches, :ssr
+
+    def initialize(status:, html:, fetches:, ssr:)
+      @ssr = ssr
+      @status = status
+      @html = html
+      @fetches = fetches.freeze
+      freeze
+    end
+
+    def self.ssr_value?(value)
+      return false unless value.is_a?(Hash)
+
+      head = value["head"]
+      value["body"].is_a?(String) && head.is_a?(Array) && head.all?(String)
+    end
+
+    def failure
+      return :http_failure unless status == 200 && html
+      return :missing_cache_evidence if fetches.empty?
+      return :ambiguous_cache_evidence unless fetches.size == 1
+      return :invalid_ssr_value unless ssr
+
+      nil
+    end
+  end
+
+  class TargetResult
+    attr_reader :path, :outcome, :initial_cache_hit
+
+    def initialize(path:, outcome:, initial_cache_hit: nil)
+      @path = path.dup.freeze
+      @outcome = outcome
+      @initial_cache_hit = initial_cache_hit
+      freeze
+    end
+
+    def self.compare(path, first, second)
+      failure = first.failure || second.failure
+      return new(path: path, outcome: failure) if failure
+
+      initial_key, initial_hit = first.fetches.fetch(0)
+      repeat_key, repeat_hit = second.fetches.fetch(0)
+      outcome = reuse_outcome(initial_key, repeat_key, repeat_hit)
+      new(path: path, outcome: outcome, initial_cache_hit: initial_hit)
+    end
+
+    def self.reuse_outcome(initial_key, repeat_key, repeat_hit)
+      return :cache_key_changed if initial_key != repeat_key
+      return :cache_not_reused unless repeat_hit
+
+      :reused
+    end
+    private_class_method :reuse_outcome
+  end
+
+  class Report
+    attr_reader :release, :results
+
+    def initialize(release:, results:)
+      @release = release.dup.freeze
+      @results = results.freeze
+      freeze
+    end
+
+    def success?
+      !results.empty? && results.all? { |result| result.outcome == :reused }
+    end
+  end
+
+  class WarmFailed < StandardError
+    attr_reader :report
+
+    def initialize(report)
+      @report = report
+      outcomes = report.results.reject { |result| result.outcome == :reused }.map(&:outcome).uniq
+      super("SSR warming could not verify cache reuse: #{outcomes.join(', ')}")
+    end
+  end
+end

data/lib/inertia_rails_ssr_cache/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 ShakaCode LLC.
+#
+# SPDX-License-Identifier: LicenseRef-InertiaRailsSsrCache
+#
+# This file is part of Inertia Rails SSR Cache. Use is governed by The
+# Inertia Rails SSR Cache License in LICENSE.md.
+
+module InertiaRailsSsrCache
+  VERSION = "0.1.0"
+end

data/lib/inertia_rails_ssr_cache/warm_job.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 ShakaCode LLC.
+#
+# SPDX-License-Identifier: LicenseRef-InertiaRailsSsrCache
+#
+# This file is part of Inertia Rails SSR Cache. Use is governed by The
+# Inertia Rails SSR Cache License in LICENSE.md.
+
+require "active_job"
+
+module InertiaRailsSsrCache
+  # Backend configuration owns fleet concurrency. This job never fans out or retries itself.
+  class WarmJob < ActiveJob::Base
+    def self.validate_environment!
+      config = Rails.application.config
+      if config.reloading_enabled?
+        raise ConfigurationError, "SSR cache warming requires config.enable_reloading = false in the job process"
+      end
+      return unless config.allow_concurrency == false
+
+      raise ConfigurationError, "SSR cache warming requires config.allow_concurrency to permit concurrent execution"
+    end
+
+    def perform(origin, paths, release)
+      self.class.validate_environment!
+      registered = InertiaRailsSsrCache.configuration
+      targets = registered.verify_targets!(origin, paths)
+      InertiaRailsSsrCache.validate_release!(release)
+      results = targets.map { |path| warm_target(origin, path, release) }
+      report = Report.new(release: release, results: results)
+      ActiveSupport::Notifications.instrument("warm.inertia_rails_ssr_cache", report: report)
+      raise WarmFailed, report unless report.success?
+
+      report
+    end
+
+    private
+
+    def warm_target(origin, path, release)
+      result = if InertiaRailsSsrCache.current_release == release
+                 first = Probe.call(origin: origin, path: path)
+                 second = Probe.call(origin: origin, path: path)
+                 TargetResult.compare(path, first, second)
+               else
+                 TargetResult.new(path: path, outcome: :release_mismatch)
+               end
+      ActiveSupport::Notifications.instrument("target.inertia_rails_ssr_cache", result: result, release: release)
+      result
+    end
+  end
+end

data/lib/inertia_rails_ssr_cache.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2026 ShakaCode LLC.
+#
+# SPDX-License-Identifier: LicenseRef-InertiaRailsSsrCache
+#
+# This file is part of Inertia Rails SSR Cache. Use is governed by The
+# Inertia Rails SSR Cache License in LICENSE.md.
+
+require "rails"
+require "inertia_rails"
+require_relative "inertia_rails_ssr_cache/version"
+require_relative "inertia_rails_ssr_cache/configuration"
+require_relative "inertia_rails_ssr_cache/result"
+require_relative "inertia_rails_ssr_cache/probe"
+require_relative "inertia_rails_ssr_cache/railtie"
+
+module InertiaRailsSsrCache
+  autoload :WarmJob, "#{__dir__}/inertia_rails_ssr_cache/warm_job"
+
+  class << self
+    def configure
+      configuration = Configuration.new
+      yield configuration
+      @configuration = configuration.validate!
+    end
+
+    def configuration
+      @configuration || raise(ConfigurationError, "register public warming targets with configure first")
+    end
+
+    def current_release
+      validate_release!(InertiaRails.configuration.version)
+    end
+
+    def validate_release!(release)
+      Configuration.validate_release(release)
+    end
+
+    def warm_later
+      registered = configuration
+      release = current_release.dup.freeze
+      WarmJob.validate_environment!
+      job = WarmJob.set(queue: registered.queue_name).perform_later(registered.origin, registered.paths, release)
+      raise ConfigurationError, "Active Job did not enqueue the warming job" unless job
+
+      job.job_id
+    end
+  end
+end

data/sig/framework_boundary.rbs

@@ -0,0 +1,31 @@
+# Copyright (c) 2026 ShakaCode LLC.
+#
+# SPDX-License-Identifier: LicenseRef-InertiaRailsSsrCache
+#
+# This file is part of Inertia Rails SSR Cache. Use is governed by The
+# Inertia Rails SSR Cache License in LICENSE.md.
+
+# These narrow interfaces describe only the framework calls used by the public facade.
+# Inertia's evaluated version can be arbitrary application data; validation narrows it.
+interface _InertiaVersionConfiguration
+  def version: () -> Object?
+end
+
+module InertiaRails
+  def self.configuration: () -> _InertiaVersionConfiguration
+end
+
+interface _EnqueuedWarmJob
+  def job_id: () -> String
+end
+
+interface _ConfiguredWarmJob
+  def perform_later: (String? origin, Array[String] paths, String release) -> (_EnqueuedWarmJob | false)
+end
+
+module InertiaRailsSsrCache
+  class WarmJob
+    def self.validate_environment!: () -> void
+    def self.set: (queue: String | Symbol) -> _ConfiguredWarmJob
+  end
+end

data/sig/inertia_rails_ssr_cache.rbs

@@ -0,0 +1,70 @@
+# Copyright (c) 2026 ShakaCode LLC.
+#
+# SPDX-License-Identifier: LicenseRef-InertiaRailsSsrCache
+#
+# This file is part of Inertia Rails SSR Cache. Use is governed by The
+# Inertia Rails SSR Cache License in LICENSE.md.
+
+module InertiaRailsSsrCache
+  self.@configuration: Configuration?
+  def self.configure: () { (Configuration) -> void } -> Configuration
+  def self.configuration: () -> Configuration
+  def self.current_release: () -> String
+  def self.validate_release!: (Object? release) -> String
+  def self.warm_later: () -> String
+  class ConfigurationError < StandardError
+  end
+
+  class Configuration
+    MAX_TARGETS: Integer
+    RELEASE: Regexp
+    INVALID_CHARACTERS: Regexp
+    attr_accessor origin: String?
+    attr_accessor paths: Array[String]
+    attr_accessor queue_name: String | Symbol
+
+    def initialize: () -> void
+    def validate!: () -> self
+    def verify_targets!: (String requested_origin, Array[String] requested_paths) -> Array[String]
+    def self.validate_release: (Object? value) -> String
+    def self.validate_queue_name: (String | Symbol value) -> String
+    def self.valid_origin?: (URI::Generic parsed) -> bool
+    def self.validate_origin: (String? value) -> String
+    def self.validate_paths: (Array[String] value) -> Array[String]
+    def self.validate_path: (String path) -> void
+  end
+
+  type outcome = :reused | :http_failure | :missing_cache_evidence | :ambiguous_cache_evidence | :invalid_ssr_value | :cache_key_changed | :cache_not_reused | :release_mismatch
+  type cache_fetch = [String, bool]
+
+  class Observation
+    attr_reader ssr: bool
+    attr_reader status: Integer
+    attr_reader html: bool
+    attr_reader fetches: Array[cache_fetch]
+    def initialize: (status: Integer, html: bool, fetches: Array[cache_fetch], ssr: bool) -> void
+    def self.ssr_value?: (Object? value) -> bool
+    def failure: () -> (:http_failure | :missing_cache_evidence | :ambiguous_cache_evidence | :invalid_ssr_value)?
+  end
+
+  class TargetResult
+    attr_reader path: String
+    attr_reader outcome: outcome
+    attr_reader initial_cache_hit: bool?
+    def initialize: (path: String, outcome: outcome, ?initial_cache_hit: bool?) -> void
+    def self.reuse_outcome: (String initial_key, String repeat_key, bool repeat_hit) -> outcome
+    def self.compare: (String path, Observation first, Observation second) -> TargetResult
+  end
+
+  class Report
+    attr_reader release: String
+    attr_reader results: Array[TargetResult]
+    def initialize: (release: String, results: Array[TargetResult]) -> void
+    def success?: () -> bool
+  end
+
+  class WarmFailed < StandardError
+    attr_reader report: Report
+    def initialize: (Report report) -> void
+  end
+end

metadata

@@ -0,0 +1,174 @@
+--- !ruby/object:Gem::Specification
+name: inertia_rails_ssr_cache
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Justin Gordon
+- ShakaCode
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: inertia_rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.22.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.22.0
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+description: Warm explicitly registered public routes through the native Inertia SSR
+  cache.
+email:
+- justin@shakacode.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.md
+- README.md
+- lib/inertia_rails_ssr_cache.rb
+- lib/inertia_rails_ssr_cache/configuration.rb
+- lib/inertia_rails_ssr_cache/probe.rb
+- lib/inertia_rails_ssr_cache/railtie.rb
+- lib/inertia_rails_ssr_cache/result.rb
+- lib/inertia_rails_ssr_cache/version.rb
+- lib/inertia_rails_ssr_cache/warm_job.rb
+- sig/framework_boundary.rbs
+- sig/inertia_rails_ssr_cache.rbs
+homepage: https://github.com/shakacode/inertia_rails_ssr_cache
+licenses:
+- LicenseRef-InertiaRailsSsrCache
+metadata:
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/shakacode/inertia_rails_ssr_cache
+  documentation_uri: https://github.com/shakacode/inertia_rails_ssr_cache#readme
+  changelog_uri: https://github.com/shakacode/inertia_rails_ssr_cache/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/shakacode/inertia_rails_ssr_cache/issues
+  license_uri: https://github.com/shakacode/inertia_rails_ssr_cache/blob/main/LICENSE.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.18
+specification_version: 4
+summary: Verified Inertia Rails SSR cache warming through Active Job.
+test_files: []