upkeep-rails 0.1.9 → 0.1.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4b31fcfa6f392fc224821b3fdd7c0ec4b98474cebaa775aacd504172c1c930e
-  data.tar.gz: a421c17550f3065d13dad7502984436a065a8d1ede670252f0b2a2187a88a785
+  metadata.gz: dc9e5c1e0ea0a632a8fea8240f0b36da735af2b8b652fa1d8f7ad40d6794f64e
+  data.tar.gz: d695df991c56c9f5a4f371cb76fbfc90b63c34404b4f3f272a8b809130395dfb
 SHA512:
-  metadata.gz: 33947d347624c6e61888db6096f71f36b8abc893fa9cbe3a8a9643c9ef91a33eed220c643086ae65dfdcea6290b5881d44d7986feb8bbc1265906673cc4b9b8b
-  data.tar.gz: b358287f543e6bb3ec9e0a254dd453d2ae134575cbfd93a2710f2b58a24ac4d1c4b7b2784498505baede37ce8027ae28340384025bac8b0fa6acc7169abd7934
+  metadata.gz: df24407ec23c61979e8f8960794a6b3ae6c7f82aacb5902780731e664e925cab32e81f48cfc3208fe9bf9d505c871169d8e5774ce5888309fb0041574adcb941
+  data.tar.gz: 2afe28057f1d6f565900fb55f3c3d6cfba2a8fe73b817c343cd95349014ea7a7fb04664b3a83a84c21bed606f2379e2f4287f5f19537d0692aab25ac018dcda0

data/README.md

@@ -1,93 +1,38 @@
 # Upkeep Rails
 
-## 0. Quick Intro
+Upkeep automatically syncs record changes to browsers showing affected data. When you save a record, it figures out which rendered pages depend on it and sends Turbo Streams to the right subscribers.
 
-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:
+Instead of naming stream targets in your controller:
 
 ```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
+    @card = Card.create!(card_params)
+    respond_to { |f| f.turbo_stream }
   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 %>
+<%= turbo_stream.append "cards", partial: "card", locals: { card: @card } %>
 ```
 
-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:
+You just save the record:
 
 ```ruby
 class CardsController < ApplicationController
   def create
-    board = Board.find(params[:board_id])
-    board.cards.create!(card_params)
-
+    Card.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.
+Upkeep observed which records the initial GET read, so it knows the page depends on the card table. When the create commits, it broadcasts to the right browsers automatically.
 
-| 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
+## Install
 
-Add the gem:
+Add the gem to your Gemfile:
 
 ```ruby
 gem "upkeep-rails"
@@ -100,68 +45,37 @@ 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.
+This creates the subscription tables, writes an initializer, mounts ActionCable if needed, and imports the browser client.
 
-Requirements: Ruby 3.2+, Rails 7.1+, and Turbo 2.0+.
+Requirements: Ruby 3.2+, Rails 7.1+, Turbo 2.0+.
 
-## 3. Configure Runtime
+## Configure runtime
 
-The generated initializer is the normal place to configure Upkeep:
+The installer creates `config/initializers/upkeep.rb`. Most projects work with the defaults, but you can customize:
 
 ```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)
+  config.subscription_store = :active_record  # :memory for tests
+  config.deliver_inline = false  # true for tests/console
+  config.refused_boundary_behavior = :warn  # :raise in strict mode
 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:
+**Subscription store:** Use `:memory` for test suites. Use `:active_record` for production—it stores subscriptions durably across restarts.
 
-```ruby
-Upkeep::Rails.configure do |config|
-  config.delivery_adapter = Rails.env.production? ? :active_job : :async
-  config.delivery_queue = :upkeep_realtime
-end
-```
+**Delivery mode:** Upkeep broadcasts from a background dispatcher in the same process that performed the write. For tests and console sessions where you want synchronous behavior, set `deliver_inline = true`.
 
-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.
+**Subscription lifecycle:** Subscriptions clean themselves up. A clean disconnect deletes the subscription immediately; abandoned subscriptions (crashed browsers, dropped connections) are trimmed opportunistically in small batches once they go untouched for `config.subscription_ttl` (default 24 hours); and connected pages send a liveness heartbeat every 20 minutes, so a long-lived open tab is never pruned. Adjust `subscription_ttl` to control how long abandoned subscriptions may linger.
 
-For local debugging, set `config.delivery_adapter = :inline` to run delivery
-immediately.
+**Multi-process deployments:** If you run multiple Puma workers, you need a cross-process cable adapter so broadcasts reach all processes. We recommend `solid_cable`.
 
-## 4. Configure Identity
+## Configure identity
 
-Pages that depend on a user, account, tenant, locale, or other viewer-specific
-value need an explicit identity bridge.
+If your pages depend on the current user, account, or any viewer-specific value, tell Upkeep how to match that between render time and subscription time.
 
-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.
+First, declare the identity in the initializer:
 
 ```ruby
-# config/initializers/upkeep.rb
 Upkeep::Rails.configure do |config|
   config.identify :viewer, current: ["Current", :user] do
     subscribe { |connection| connection.current_user }
@@ -169,10 +83,9 @@ Upkeep::Rails.configure do |config|
 end
 ```
 
-The matching cable connection must expose that identity:
+Then make sure your cable connection exposes it:
 
 ```ruby
-# app/channels/application_cable/connection.rb
 module ApplicationCable
   class Connection < ActionCable::Connection::Base
     identified_by :current_user
@@ -184,128 +97,125 @@ module ApplicationCable
 end
 ```
 
-Choose the source keyword from the API your render path actually reads:
+Pick the declaration that matches how your render path reads the identity:
 
-| Render path reads | Declare | Subscribe side returns |
+| Render path | Configuration | Subscribe 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` |
+| `Current.user` | `current: ["Current", :user]` | `connection.current_user` |
+| Devise/Warden | `warden: :user` | `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:
+For logged-out pages where `nil` is a valid identity, declare how to recognize "absent":
 
 ```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
+config.identify :viewer, session: :user_id do
+  absent_if { |value| value.nil? || value == false }
+  subscribe { |connection| connection.session[:user_id] }
 end
 ```
 
-If a page reads an undeclared non-absent `CurrentAttributes` or Warden identity,
-Upkeep refuses live registration instead of guessing who may receive updates.
+If your render path reads an undeclared identity value (like a `CurrentAttributes` field), Upkeep will refuse to register that page for live updates rather than guess who should receive the broadcast.
 
-## 5. Opaque Values, DX, and Refactors
+## When Upkeep can't track your data
 
-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.
+Upkeep needs to understand your queries to know which records affect which renders. It can't work with raw SQL strings, opaque joins, or objects that aren't tied back to the database schema.
 
-`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.
+These queries will cause Upkeep to refuse the page:
 
-The DX is intentionally fail-fast:
+```ruby
+# Raw SQL predicates
+Story.where("score >= 0")
+Story.order("created_at DESC")
 
-- 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
+# Opaque joins
+User.joins("INNER JOIN posts ON ...")
+
+# From sources that aren't table names
+Story.from("(SELECT * FROM stories WHERE ...)")
+```
 
-You can choose the behavior explicitly:
+Rewrite them using Rails or Arel:
+
+```ruby
+Story.where(Story.arel_table[:score].gteq(0))
+Story.order(created_at: :desc)
+```
+
+By default, Upkeep raises an error in development and test, and logs a warning in production (but still renders the page). You can change this behavior:
 
 ```ruby
 Upkeep::Rails.configure do |config|
-  config.refused_boundary_behavior = :raise # or :warn
+  config.refused_boundary_behavior = :warn  # or :raise
 end
 ```
 
-Most refactors are normal Rails cleanup. Prefer hash conditions and symbolic
-orders when they express the query:
+For queries that genuinely can't be made structural—like full-text search backed by raw `tsvector`—opt the request out entirely instead:
 
 ```ruby
-# Before: opaque SQL string order
-Story.order("stories.created_at DESC")
+class StoriesController < ApplicationController
+  def index
+    @stories = params[:query].present? ? Story.search(params[:query]) : Story.all
+  end
 
-# After: structural Rails order
-Story.order(created_at: :desc)
+  private
+
+  def upkeep_reactive_request?
+    return false if params[:query].present?
+    super
+  end
+end
 ```
 
-Use Arel when the query needs an operator or correlated condition that hash
-syntax cannot express:
+The request still renders normally. Upkeep just doesn't register subscriptions or analyze the boundary. The unfiltered view (without a query param) stays reactive.
 
-```ruby
-# Before: opaque SQL string predicate
-Story.where("score >= 0")
+**General rule:** if Rails or Arel can describe the table, columns, predicates, and sort order, Upkeep can track it. If the query logic lives inside a SQL string, Upkeep will refuse the page.
 
-# After: structural Arel predicate
-Story.where(Story.arel_table[:score].gteq(0))
-```
+## How Upkeep compares to Turbo Streams
+
+With vanilla Turbo Streams, the write action names which parts of the UI to refresh. You maintain the list of targets as your UI evolves:
 
 ```ruby
-# Before: opaque correlated SQL
-HiddenStory.where(Arel.sql("hidden_stories.story_id = stories.id"))
+class CardsController < ApplicationController
+  def create
+    @board = Board.find(params[:board_id])
+    @card = @board.cards.create!(card_params)
+    
+    respond_to do |format|
+      format.turbo_stream
+    end
+  end
+end
+```
 
-# After: structural correlated predicate
-HiddenStory.where(
-  HiddenStory.arel_table[:story_id].eq(Story.arel_table[:id])
-)
+```erb
+<%= turbo_stream.append "cards", partial: "card", locals: { card: @card } %>
+<%= turbo_stream.update "board_open_count", @board.open_count %>
 ```
 
-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.
+This couples the write path to the current UI. When you add a sidebar showing the same board, or a filter that depends on card status, you revisit the controller and stream template.
 
-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:
+With Upkeep, the write path just saves the record. The subscription comes from the read:
 
 ```ruby
-# app/controllers/stories_controller.rb
-def index
-  @stories = params[:query].present? ? Story.search(params[:query]) : Story.recent
+class CardsController < ApplicationController
+  def create
+    Board.find(params[:board_id]).cards.create!(card_params)
+    head :no_content
+  end
 end
+```
 
-private
+Upkeep observed which records your initial GET read, so it knows which renders care about this card. It broadcasts to those subscribers automatically. You add a sidebar or filter without touching the write path.
 
-# 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?
+The tradeoff: Turbo Streams let you control exactly what gets broadcast and how it's rendered (you might patch a counter without rerendering the list). Upkeep derives updates from renders it observed, so it's narrower but also more opinionated about safety.
 
-  super
-end
-```
+| Concern | Turbo Streams | Upkeep |
+| --- | --- | --- |
+| Write path | Declares targets and templates | Just commits the record |
+| Boundary discovery | You maintain it | Upkeep infers from renders |
+| Unsafe broadcasts | You decide how broad | Upkeep refuses unsafe patterns |
+| Render changes | Update the stream template | Happens automatically |
+| Full control | Yes | No, but less coupling |
 
-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.
+See [How Upkeep Works](docs/how-it-works.md) for details on the runtime model.