upkeep-rails 0.1.9

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a4b31fcfa6f392fc224821b3fdd7c0ec4b98474cebaa775aacd504172c1c930e
+  data.tar.gz: a421c17550f3065d13dad7502984436a065a8d1ede670252f0b2a2187a88a785
+SHA512:
+  metadata.gz: 33947d347624c6e61888db6096f71f36b8abc893fa9cbe3a8a9643c9ef91a33eed220c643086ae65dfdcea6290b5881d44d7986feb8bbc1265906673cc4b9b8b
+  data.tar.gz: b358287f543e6bb3ec9e0a254dd453d2ae134575cbfd93a2710f2b58a24ac4d1c4b7b2784498505baede37ce8027ae28340384025bac8b0fa6acc7169abd7934

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felipe Anjos
+
+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

@@ -0,0 +1,311 @@
+# Upkeep Rails
+
+## 0. Quick Intro
+
+Upkeep Rails keeps ordinary Rails pages fresh when the data, request inputs, or
+identity values they used change.
+
+A successful HTML GET renders through Rails as usual. Upkeep records the
+templates, records, relations, request values, and identity values that shaped
+the response. Later, an Active Record commit emits facts about what changed.
+Upkeep matches those facts to affected rendered frames and delivers ordinary
+Turbo Stream updates over ActionCable.
+
+The design goal is Rails-shaped DX: controllers load state, views render ERB,
+models commit writes, and Upkeep derives the reactive boundary from the Rails
+surfaces it observes. There is no query catalog and no `watch` or `track` DSL.
+
+For the deeper runtime model, see [How Upkeep Works](docs/how-it-works.md).
+
+## 1. Upkeep vs Vanilla Turbo
+
+With vanilla Turbo Streams, write paths often need to name the UI they refresh:
+
+```ruby
+# app/controllers/cards_controller.rb
+class CardsController < ApplicationController
+  def create
+    @board = Board.find(params[:board_id])
+    @card = @board.cards.new(card_params)
+
+    if @card.save
+      @open_card_count = @board.cards.open.count
+
+      respond_to do |format|
+        format.turbo_stream
+      end
+    else
+      render :new, status: :unprocessable_entity
+    end
+  end
+end
+```
+
+```erb
+<%# app/views/cards/create.turbo_stream.erb %>
+<%= turbo_stream.append "cards",
+  partial: "cards/card",
+  locals: { card: @card } %>
+
+<%= turbo_stream.update "open_card_count", @open_card_count %>
+```
+
+That follows the standard Turbo Stream shape and avoids a page visit for the
+submitting browser. The tradeoff is that the write path is still coupled to the
+current UI. Adding another dependent page, sidebar, filter, or counter usually
+means revisiting stream templates, controller assignments, callbacks, or
+broadcasts.
+
+With Upkeep, the controller can acknowledge the successful write without naming
+stream targets:
+
+```ruby
+class CardsController < ApplicationController
+  def create
+    board = Board.find(params[:board_id])
+    board.cards.create!(card_params)
+
+    head :no_content
+  end
+end
+```
+
+The submitting Turbo request gets a successful empty response, so it does not
+perform a page visit. The GET that rendered the page already recorded the
+rendered dependencies. When the commit lands, Upkeep selects affected
+subscribers and sends Turbo Streams to the browsers that need them. Validation
+and error rendering stay ordinary application code; the live update path does
+not need to name DOM targets.
+
+| Concern | Vanilla Turbo | Upkeep |
+| --- | --- | --- |
+| Write path | Names stream targets, partials, counters, or pages. | Commits domain changes. |
+| Read path | Ordinary Rails render. | Ordinary Rails render, captured during HTML GETs. |
+| Browser update | Turbo Streams or page refresh. | Turbo Streams or page refresh. |
+| Boundary | App declares it in stream templates, callbacks, or broadcasts. | Upkeep derives it from rendered Rails surfaces when it can prove safety. |
+| Unsafe shape | App decides how broad to broadcast. | Upkeep raises or warns and refuses the live boundary. |
+
+## 2. Install
+
+Add the gem:
+
+```ruby
+gem "upkeep-rails"
+```
+
+Run the installer:
+
+```sh
+bin/rails generate upkeep:install
+bin/rails db:migrate
+```
+
+The generator creates subscription tables, writes
+`config/initializers/upkeep.rb`, mounts ActionCable when needed, pins Turbo and
+ActionCable for importmap apps, and imports the browser bootstrap from
+`app/javascript/application.js`.
+
+The browser bootstrap is vendored into the host app at
+`app/javascript/upkeep/subscription.js`. After upgrading `upkeep-rails`, rerun
+the installer or compare that file with the generated template.
+
+Requirements: Ruby 3.2+, Rails 7.1+, and Turbo 2.0+.
+
+## 3. Configure Runtime
+
+The generated initializer is the normal place to configure Upkeep:
+
+```ruby
+# config/initializers/upkeep.rb
+Upkeep::Rails.configure do |config|
+  app_config = Rails.application.config.upkeep
+
+  config.enabled = app_config.fetch(:enabled, true)
+  config.subscription_store = app_config.fetch(:subscription_store, Rails.env.test? ? :memory : :active_record)
+  config.delivery_adapter = app_config.fetch(:delivery_adapter, Rails.env.production? ? :active_job : :async)
+  config.delivery_queue = app_config.fetch(:delivery_queue, :upkeep_realtime)
+end
+```
+
+Use `:active_record` for durable subscription storage in production. The
+generated migration creates the required tables. Use `:memory` for most request
+and system tests, and keep at least one app or CI path on `:active_record` when
+you want to exercise durable rows, schema checks, reload, and cross-process
+lookup.
+
+Production apps should use Active Job for delivery so planning, rerendering,
+and broadcasting do not run in the writer's request:
+
+```ruby
+Upkeep::Rails.configure do |config|
+  config.delivery_adapter = Rails.env.production? ? :active_job : :async
+  config.delivery_queue = :upkeep_realtime
+end
+```
+
+Configure the app's Active Job backend normally, such as Solid Queue, Sidekiq,
+or GoodJob. ActionCable still needs a shared adapter in multi-process
+deployments because a job worker may not be the process holding the browser's
+WebSocket. Redis, Solid Cable, and PostgreSQL are shared ActionCable adapters.
+
+For local debugging, set `config.delivery_adapter = :inline` to run delivery
+immediately.
+
+## 4. Configure Identity
+
+Pages that depend on a user, account, tenant, locale, or other viewer-specific
+value need an explicit identity bridge.
+
+The render side tells Upkeep which value the HTML render read. The subscribe
+side tells Upkeep how the ActionCable connection proves the same value when the
+browser subscribes.
+
+```ruby
+# config/initializers/upkeep.rb
+Upkeep::Rails.configure do |config|
+  config.identify :viewer, current: ["Current", :user] do
+    subscribe { |connection| connection.current_user }
+  end
+end
+```
+
+The matching cable connection must expose that identity:
+
+```ruby
+# app/channels/application_cable/connection.rb
+module ApplicationCable
+  class Connection < ActionCable::Connection::Base
+    identified_by :current_user
+
+    def connect
+      self.current_user = User.find_by(id: request.session[:user_id])
+    end
+  end
+end
+```
+
+Choose the source keyword from the API your render path actually reads:
+
+| Render path reads | Declare | Subscribe side returns |
+| --- | --- | --- |
+| `Current.user` | `current: ["Current", :user]` | the same user, usually `connection.current_user` |
+| Devise or Warden user reads | `warden: :user` | the same Devise user, usually `connection.current_user` |
+| `session[:user_id]` | `session: :user_id` | `connection.session[:user_id]` |
+| `cookies[:account_id]` | `cookie: :account_id` | `connection.cookies[:account_id]` |
+
+By default, `nil` means a declared identity boundary is absent. That keeps
+logged-out pages anonymous-public even when a layout checks `Current.user` or
+`session[:user_id]`. If your app has another "not signed in" sentinel, declare
+it:
+
+```ruby
+Upkeep::Rails.configure do |config|
+  config.identify :viewer, session: :user_id do
+    absent_if { |value| value.nil? || value == false }
+    subscribe { |connection| connection.session[:user_id] }
+  end
+end
+```
+
+If a page reads an undeclared non-absent `CurrentAttributes` or Warden identity,
+Upkeep refuses live registration instead of guessing who may receive updates.
+
+## 5. Opaque Values, DX, and Refactors
+
+Upkeep only registers live boundaries it can prove. It needs to know which
+future write facts can make a rendered result stale, which target can be
+rerendered or patched, and which observed identity inputs decide whether the
+result can be shared.
+
+`Opaque` means application code used something real, but Rails did not expose
+enough structure for Upkeep to answer those questions. Common examples are raw
+SQL predicates, raw joins, raw `from` sources, unknown table aliases, opaque
+order expressions, and render locals that cannot be rebuilt later.
+
+The DX is intentionally fail-fast:
+
+- development and test raise by default
+- production warns and skips live registration by default
+- `refused_boundary.upkeep` is emitted for instrumentation
+- Upkeep does not widen to a broad unsafe dependency
+
+You can choose the behavior explicitly:
+
+```ruby
+Upkeep::Rails.configure do |config|
+  config.refused_boundary_behavior = :raise # or :warn
+end
+```
+
+Most refactors are normal Rails cleanup. Prefer hash conditions and symbolic
+orders when they express the query:
+
+```ruby
+# Before: opaque SQL string order
+Story.order("stories.created_at DESC")
+
+# After: structural Rails order
+Story.order(created_at: :desc)
+```
+
+Use Arel when the query needs an operator or correlated condition that hash
+syntax cannot express:
+
+```ruby
+# Before: opaque SQL string predicate
+Story.where("score >= 0")
+
+# After: structural Arel predicate
+Story.where(Story.arel_table[:score].gteq(0))
+```
+
+```ruby
+# Before: opaque correlated SQL
+HiddenStory.where(Arel.sql("hidden_stories.story_id = stories.id"))
+
+# After: structural correlated predicate
+HiddenStory.where(
+  HiddenStory.arel_table[:story_id].eq(Story.arel_table[:id])
+)
+```
+
+For replay values, keep frame locals and render options to records, relations,
+arrays, hashes, literals, and observed request, session, or cookie values. Avoid
+passing procs, IO handles, open clients, or process-local objects into live
+render boundaries.
+
+Some boundaries are intractable on purpose. A full-text search backed by raw
+`tsvector`/`tsquery` SQL has no structural column coverage to prove, and
+rewriting it would defeat the search. When a request should not be made
+reactive at all, opt it out instead of refusing a boundary mid-render. Override
+`upkeep_reactive_request?` in the controller and return `false` for those
+requests:
+
+```ruby
+# app/controllers/stories_controller.rb
+def index
+  @stories = params[:query].present? ? Story.search(params[:query]) : Story.recent
+end
+
+private
+
+# Search results use a raw full-text scope Upkeep cannot prove; render them
+# normally but do not register them for live refresh.
+def upkeep_reactive_request?
+  return false if params[:query].present?
+
+  super
+end
+```
+
+An opted-out request still runs the action and renders the page; Upkeep simply
+records no subscription, injects no source, and analyzes no boundary — so an
+opaque relation on that request neither raises nor warns. The unfiltered page
+(no `query`) stays reactive. Reach for this only when the boundary is
+genuinely unprovable; prefer the structural refactors above whenever the shape
+*can* be made explicit.
+
+The rule of thumb: when Rails and Arel can describe the table, column,
+predicate, order, and value shape, Upkeep can usually reason about it. When the
+shape is hidden inside a string or arbitrary Ruby object, Upkeep refuses the
+live boundary and tells you where to make the shape explicit.

data/docs/how-it-works.md

@@ -0,0 +1,269 @@
+# How Upkeep Works
+
+This document explains the runtime model behind Upkeep Rails. It intentionally
+does not cover installation or common configuration; use the
+[README](../README.md) for that public API surface.
+
+## Rendered Pages
+
+A rendered page is a successful HTML GET that Upkeep can keep fresh. The
+request runs normally through Rails. Upkeep observes the controller, Action View
+rendering, Active Record reads, request inputs, and identity inputs used by the
+response.
+
+Upkeep only captures successful HTML responses. Non-HTML responses, redirects,
+failed responses, and explicit non-page interactions continue to behave like
+ordinary Rails responses.
+
+## Frames
+
+A frame is a rendered page, template, partial, collection render site, or
+fragment with a stable delivery target.
+
+Frames let Upkeep refresh a specific part of the page instead of replaying the
+whole response when a narrower update is proven safe. A page frame is the broad
+fallback. A render-site or fragment frame is narrower.
+
+Upkeep instruments Action View templates and adds internal `data-upkeep-*`
+markers for page roots, fragment roots, and safe collection render-site
+containers. Normal templates do not need to call helper APIs directly.
+
+The `upkeep_frame` helper is an advanced escape hatch for generated or
+helper-built boundaries that cannot be derived from template source. Ordinary
+ERB and partial collections should not need it.
+
+## Surfaces
+
+A surface is the set of facts about future writes that would make a frame
+stale.
+
+For Active Record, Upkeep derives surfaces from observed record attributes,
+rendered collections, and relation shape where Rails exposes structural Arel
+queries. A rendered collection of open cards ordered by position produces a
+surface tied to the cards table, the columns that decide membership and order,
+and the records rendered in that collection.
+
+When a write commits, Upkeep compares the write facts with registered surfaces.
+Only frames whose surfaces can be affected are selected for delivery.
+
+## Identity Boundaries
+
+An identity boundary is state that decides who may receive a live update.
+
+Upkeep records observed CurrentAttributes, Warden, session, cookie, and request
+reads for replay and sharing. It does not infer subscriber identity by naming
+convention. The app declares which render-time value maps to which
+subscribe-time ActionCable value.
+
+The safety rule is simple: if rendered output depends on a non-public identity,
+only subscribers proving the same identity may receive that output. If Upkeep
+cannot identify the boundary, it refuses live registration rather than sending
+viewer-specific HTML to the wrong browser.
+
+Absent identities are public. For example, if a logged-out page reads a nil
+viewer, that nil value can be treated as anonymous-public instead of
+subscriber-specific.
+
+## Subscriptions
+
+A subscription is the browser's live connection back to the captured page.
+
+Upkeep injects a body-scoped `<upkeep-subscription-source>` marker into
+successful HTML responses. The generated browser bootstrap upgrades that marker
+into a Turbo stream source, subscribes over ActionCable, and lets Turbo process
+received stream payloads.
+
+The server stores a replayable subscription graph for the rendered page. The
+graph contains frames, dependencies, target metadata, replay recipes, request
+inputs, and identity information needed to plan later updates.
+
+## Proven Delivery
+
+Proven delivery means Upkeep only emits the narrowest Turbo operation it can
+justify.
+
+Depending on the proof available, delivery may use:
+
+- `append`
+- `prepend`
+- `remove`
+- `replace`
+- `update`
+- Turbo page `refresh`
+
+Render-site replays use Turbo Stream `update method="morph"` against the real
+HTML element Upkeep marked as the render site. The stream template is the
+render site's children, so `update` preserves the legal container element and
+swaps its contents.
+
+Page-level fallbacks use Turbo Stream `refresh method="morph"
+scroll="preserve"` instead of replacing `<html>` or writing a new document from
+JavaScript.
+
+## Deoptimization
+
+A deoptimization means Upkeep can still prove correctness, but not the cheapest
+operation.
+
+For example, a collection member update might not have enough proof for a
+single member `replace`, but the enclosing render site might still be safe to
+rerender. In that case, the page remains live and Upkeep falls back to the
+broader proven target.
+
+Planning and delivery telemetry record deoptimization reasons so benchmarks and
+tests can separate safety fallbacks from true refusals.
+
+## Refused Boundaries
+
+A refused boundary means Upkeep cannot prove correctness.
+
+If Upkeep cannot answer which future write facts can make a rendered result
+stale, which target can be replayed or patched, or which identity inputs decide
+sharing, it refuses the live boundary.
+
+This is intentional. A boundary that cannot be proven should behave like
+ordinary Rails HTML instead of registering a broad or unsafe live dependency.
+
+Refusal is different from deoptimization:
+
+- refusal: Upkeep cannot prove correctness, so the boundary is not live
+- deoptimization: Upkeep can prove correctness through a broader target, so the
+  boundary remains live
+
+## What Upkeep Observes
+
+Render structure:
+
+- Rails-resolved page templates
+- partial and object partial renders
+- Action View-instrumented collection render sites and child fragments
+- polymorphic `render @records` collection shorthand when runtime rendering
+  confirms a collection
+- `tag.*` and `content_tag` containers lowered by Herb into ordinary template
+  structure
+- single-root fragment targets and legal render-site container targets
+
+Template parsing:
+
+- Upkeep plans narrow source-derived targets only from templates that pass
+  Herb's strict parser.
+- If strict parsing fails but Herb can recover with `strict: false`, Upkeep
+  reports the strict parser diagnostics as warnings and may still add broad
+  page or fragment root markers.
+- Recovered render sites are diagnostic only. Fix strict warnings before
+  expecting narrow collection updates from that template.
+
+Data dependencies:
+
+- Active Record attribute reads
+- Active Record relation collection renders
+- Active Record callback writes
+- supported bulk `update_all` and `delete_all` writes
+- relation table and column coverage derived from Arel where Rails exposes a
+  structural query shape
+
+Identity and ambient inputs:
+
+- `ActiveSupport::CurrentAttributes` reads
+- Warden and Devise user reads through Warden
+- session and cookie reads
+- request values such as host, path, params, user agent, and remote IP
+- declared Upkeep identities that map observed render-time values to
+  ActionCable subscribe-time values
+
+## What Upkeep Cannot Capture
+
+Upkeep captures reactive facts, not arbitrary Ruby execution. A boundary is
+capturable only when Upkeep can prove the future write facts that affect it,
+the target that can be replayed or patched, and the identity inputs that decide
+whether it can be shared.
+
+These surfaces are not capturable today:
+
+| Surface | Why it is not capturable | Runtime behavior |
+| --- | --- | --- |
+| Opaque Active Record relations: raw SQL predicates, raw joins, raw `from` sources, unknown table aliases, opaque order expressions, or opaque pluck columns. | Rails no longer exposes enough structure to prove table, column, predicate, and lifecycle coverage. | Upkeep refuses the live boundary instead of widening to an unsafe dependency. |
+| Controller queries that are never rendered as a collection boundary. | There is no DOM collection surface where membership can be appended, removed, prepended, or replaced. | The page can still render normally. Scalar relation output may be tracked as a page-level dependency, but it does not unlock collection stream planning. |
+| Reads from external stores or process state: Redis, HTTP APIs, files, global variables, class variables, singleton caches, background thread state, or service memoization. | Active Record commit facts cannot select these reads, and Upkeep has no source adapter for their lifecycle. | They are not live dependencies. If another observed dependency causes a replay, normal Rails code may read the new value during that replay. |
+| Writes outside observed Active Record paths: direct connection SQL, writes in another datastore, or side effects that do not emit Upkeep change facts. | Upkeep cannot match a future change to an existing surface without a write fact. | No refresh is scheduled from that write. |
+| Replay inputs that cannot be rebuilt: arbitrary objects, procs, IO handles, open clients, or values that only exist in one Ruby process. | A captured target must be replayable later, often in a different request context. | Non-replayable values block the narrow replay path until represented as stable data. |
+| Patch targets Upkeep cannot identify in rendered HTML. | Delivery needs a stable page, render-site, fragment, or member target. | Upkeep uses the narrowest proven target. If no safe target exists, the boundary is refused. |
+
+## Query Shapes
+
+Collection dependencies are accepted only with proven column coverage. Opaque
+predicates or table-only sources are refused instead of widening into broad
+invalidation.
+
+Controller materialization is supported when the rendered value keeps a
+structural relation proof:
+
+```ruby
+def index
+  @cards = Card.where(status: "open").order(:position).to_a
+end
+```
+
+```erb
+<%= render partial: "cards/card", collection: @cards, as: :card %>
+```
+
+Upkeep attaches the collection dependency to the rendered collection boundary,
+not to every controller query. A materialized relation that is never rendered as
+a collection is not a lifecycle dependency by itself.
+
+Scalar relation output is tracked as a page-level query dependency:
+
+```ruby
+@tag_names = Tag.where(active: true).pluck(:name)
+```
+
+Simple plucked columns are live and can select a page replay when they change.
+They are not collection dependencies, so they do not participate in
+append/remove/prepend planning.
+
+## Testing Model
+
+Use `Upkeep::Rails::Testing` for app-level assertions around subscription
+registration and delivery.
+
+Structure tests around behavior, not store internals:
+
+- Most request and system tests can run against the memory store. Memory has
+  the same public lifecycle as ActiveRecord: registration is fetchable
+  immediately, lookup visibility starts on activation, touch updates liveness,
+  unregister and prune remove lookup entries, and delivery uses the same
+  planner surface.
+- Keep a smaller ActiveRecord-backed integration slice for production-only
+  concerns: generated migration shape, schema validation, durable rows,
+  reload and rehydration, async persistence, and cross-process lookup.
+- Do not assert implementation details that are unique to one store unless the
+  test is explicitly about that implementation. For app behavior, assert the
+  marker, activation, streams, broadcasts, and rendered bytes.
+
+Useful helpers:
+
+- `assert_upkeep_subscription_registered`
+- `upkeep_subscription`
+- `upkeep_stream_names`
+- `activate_upkeep_subscription!`
+- `capture_upkeep_broadcasts`
+- `drain_upkeep_delivery!`
+- `capture_upkeep_change_facts`
+- `upkeep_match_report`
+
+Use `capture_upkeep_broadcasts` when an app test needs to assert rendered
+Turbo Stream payloads without depending on the host app's Action Cable test
+adapter. The helper captures Upkeep delivery after planning and rendering, but
+before the transport broadcasts.
+
+Use `capture_upkeep_change_facts` and `upkeep_match_report` when debugging an
+invalidation miss. Capture the committed facts produced by the request, then
+dry-run them against the current subscription store. The report returns the
+candidate count, matched count, miss reason, and render targets without
+broadcasting.
+
+For structural subscription debugging, call `subscription.explain` or
+`Upkeep::Rails.subscriptions.explain(subscription.id)`. Explanations summarize
+the dependency tables and attributes, identity, frame count, lookup keys, and
+metadata without requiring store-specific instance-variable inspection.