upkeep-rails 0.1.9 → 0.1.12

data/lib/upkeep/dependencies.rb

@@ -54,10 +54,13 @@ module Upkeep
     end
 
     class ActiveRecordAttribute < Base
-      def initialize(table:, id:, attribute:, model: nil)
+      def initialize(table:, id:, attribute:, model: nil, scope: nil)
+        scope = normalize_scope(scope)
+        key = { table: table, id: id, attribute: attribute }
+        key[:scope] = scope if scope
         super(
           source: :active_record_attribute,
-          key: { table: table, id: id, attribute: attribute },
+          key: key,
           metadata: { model: model }.compact
         )
       end
@@ -65,7 +68,8 @@ module Upkeep
       def matches_change?(change)
         key.fetch(:table) == change.fetch(:table) &&
           (key.fetch(:id).nil? || !change[:id] || key.fetch(:id) == change[:id]) &&
-          change.fetch(:changed_attributes, []).include?(key.fetch(:attribute))
+          change.fetch(:changed_attributes, []).include?(key.fetch(:attribute)) &&
+          scope_matches_change?(change)
       end
 
       def precision
@@ -75,6 +79,37 @@ module Upkeep
       def narrow_frame_safe?
         true
       end
+
+      private
+
+      def normalize_scope(scope)
+        return nil unless scope.is_a?(Hash)
+
+        normalized = scope.each_with_object({}) do |(column, value), result|
+          result[column.to_s] = value unless value.nil?
+        end
+        normalized.empty? ? nil : normalized
+      end
+
+      def scope_matches_change?(change)
+        scope = key[:scope]
+        return true unless scope
+
+        scope.all? do |column, value|
+          observed = observed_scope_values(change, column)
+          observed.empty? || observed.any? { |observed_value| scope_values_equal?(observed_value, value) }
+        end
+      end
+
+      def observed_scope_values(change, column)
+        [change[:new_values], change[:old_values]].compact.filter_map do |values|
+          values[column] || values[column.to_sym]
+        end
+      end
+
+      def scope_values_equal?(observed, expected)
+        observed == expected || observed.to_s == expected.to_s
+      end
     end
 
     class ActiveRecordCollection < Base
@@ -363,12 +398,19 @@ module Upkeep
     end
 
     class RequestValue < Identity
+      # Request values that are stable for a deployment/connection rather than a viewer.
+      # They never partition subscribers, but their fingerprints are folded into shared
+      # stream names (see SharedStreams.deployment_signature_for) so viewers with
+      # different values can never share a stream.
+      DEPLOYMENT_STABLE_KEYS = %w[host port protocol ssl request_method].freeze
+
       def initialize(key:, value:)
         super(
           source: :request,
           key: key.to_s,
           value: Dependencies.private_fingerprint(value),
-          metadata: { key: key.to_s, value_class: value.class.name }
+          metadata: { key: key.to_s, value_class: value.class.name },
+          partitioning: DEPLOYMENT_STABLE_KEYS.include?(key.to_s) ? false : nil
         )
       end
     end
@@ -421,7 +463,8 @@ module Upkeep
           table: key.fetch(:table),
           id: key.fetch(:id),
           attribute: key.fetch(:attribute),
-          model: metadata[:model]
+          model: metadata[:model],
+          scope: key[:scope]
         )
       when :active_record_collection, :active_record_query
         dependency_class = source.to_sym == :active_record_query ? ActiveRecordQuery : ActiveRecordCollection
@@ -488,6 +531,13 @@ module Upkeep
       !nil_identity?(dependency)
     end
 
+    def deployment_stable_request?(dependency)
+      return false unless dependency.identity?
+      return false unless dependency.source.to_s == "request"
+
+      RequestValue::DEPLOYMENT_STABLE_KEYS.include?(dependency.key.fetch(:key).to_s)
+    end
+
     def identity_absent_for?(dependency, name)
       absent_by_name = metadata_value(dependency, :identity_absent_by_name) || {}
       absent_by_name = absent_by_name.transform_keys(&:to_s) if absent_by_name.respond_to?(:transform_keys)

data/lib/upkeep/invalidation/planner.rb

@@ -14,6 +14,7 @@ module Upkeep
         :frame_id,
         :identity_signature,
         :sharing_signature,
+        :deployment_signature,
         :recipe,
         :matched_dependency_keys,
         :action,
@@ -32,7 +33,7 @@ module Upkeep
         end
       end
 
-      Plan = Data.define(:targets, :candidate_entries, :matched_entries) do
+      Plan = Data.define(:targets, :candidate_entries, :matched_entries, :request_id) do
         def summary
           {
             targets: targets.size,
@@ -74,7 +75,7 @@ module Upkeep
             )
           end
 
-          plan = Plan.new(deduplicate_targets(targets), candidate_entries, matched_entries)
+          plan = Plan.new(deduplicate_targets(targets), candidate_entries, matched_entries, request_id_for(changes))
           payload.merge!(payload_for(plan))
           plan
         end
@@ -86,6 +87,12 @@ module Upkeep
 
       attr_reader :store
 
+      # All changes in a set were captured during one request, so the first stamped
+      # request id speaks for the whole plan. Writes from jobs/console carry none.
+      def request_id_for(changes)
+        changes.filter_map { |change| change[:request_id] if change.respond_to?(:[]) }.first
+      end
+
       def payload_for(plan)
         {
           candidate_entries: plan.candidate_entries.size,
@@ -152,7 +159,8 @@ module Upkeep
         shared_stream_target = target
         identity_signature = subscription.identity_signature(frame_id)
         sharing_signature = SharedStreams.signature_for(recipe) if shared_delivery && identity_signature == "public" && frame.payload.fetch(:kind) == "render_site"
-        action, recipe, delivery_target, deoptimization_reason = cached_delivery_strategy(frame, recipe, entries, changes, sharing_signature: sharing_signature)
+        deployment_signature = SharedStreams.deployment_signature_for(subscription.graph, frame.id) if sharing_signature
+        action, recipe, delivery_target, deoptimization_reason = cached_delivery_strategy(subscription.graph, frame, recipe, entries, changes, sharing_signature: sharing_signature)
         target = delivery_target || target
         subscriber_ids = represented_subscriber_ids(subscription, entries)
 
@@ -165,6 +173,7 @@ module Upkeep
           frame_id,
           identity_signature,
           sharing_signature,
+          deployment_signature,
           recipe,
           dependency_keys,
           action,
@@ -179,12 +188,12 @@ module Upkeep
         subscriber_ids
       end
 
-      def cached_delivery_strategy(frame, recipe, entries, changes, sharing_signature:)
+      def cached_delivery_strategy(graph, frame, recipe, entries, changes, sharing_signature:)
         key = delivery_strategy_cache_key(frame, recipe, entries, changes, sharing_signature)
-        return delivery_strategy(frame, recipe, entries, changes) unless key
+        return delivery_strategy(graph, frame, recipe, entries, changes) unless key
 
         @delivery_strategy_cache.fetch(key) do
-          @delivery_strategy_cache[key] = delivery_strategy(frame, recipe, entries, changes)
+          @delivery_strategy_cache[key] = delivery_strategy(graph, frame, recipe, entries, changes)
         end
       end
 
@@ -211,7 +220,7 @@ module Upkeep
         end
       end
 
-      def delivery_strategy(frame, recipe, entries, changes)
+      def delivery_strategy(graph, frame, recipe, entries, changes)
         remove_recipe = remove_recipe_for(frame, recipe, entries, changes)
         if remove_recipe
           return [
@@ -234,7 +243,7 @@ module Upkeep
           return ["replace", member_replace_recipe, delivery_target, nil]
         end
 
-        [fallback_action_for(frame), recipe, nil, deoptimization_reason(frame, entries, changes)]
+        [fallback_action_for(frame), recipe, nil, deoptimization_reason(graph, frame, entries, changes)]
       end
 
       def fallback_action_for(frame)
@@ -292,8 +301,16 @@ module Upkeep
         CollectionRemove.build(recipe: recipe, change: destroy_changes.first)
       end
 
-      def deoptimization_reason(frame, entries, changes)
-        return unless frame.payload.fetch(:kind) == "render_site"
+      def deoptimization_reason(graph, frame, entries, changes)
+        case frame.payload.fetch(:kind)
+        when "page"
+          page_frame_deoptimization_reason(graph, frame, entries)
+        when "render_site"
+          render_site_deoptimization_reason(entries, changes)
+        end
+      end
+
+      def render_site_deoptimization_reason(entries, changes)
         return unless entries.any? { |entry| entry.dependency.source == :active_record_collection }
 
         if changes.one? { |change| change[:id] && change.fetch(:type).to_s.include?("create") }
@@ -307,6 +324,25 @@ module Upkeep
         end
       end
 
+      def page_frame_deoptimization_reason(graph, frame, entries)
+        return "no_render_site" unless contains_render_site?(graph, frame)
+
+        "page_frame_dependency:#{entries.map { |entry| dependency_source_label(entry.dependency) }.min}"
+      end
+
+      def contains_render_site?(graph, frame)
+        graph.contained_node_ids(frame.id).any? do |node_id|
+          node = graph.node(node_id)
+          node.kind == :frame && node.payload[:kind] == "render_site" && node.payload[:recipe]
+        end
+      end
+
+      def dependency_source_label(dependency)
+        return dependency.source.to_s unless dependency.identity?
+
+        "#{dependency.source}:#{dependency.key.fetch(:key)}"
+      end
+
       def destroy_change?(change)
         type = change.fetch(:type).to_s
         type.include?("destroy") || type.include?("delete")
@@ -332,6 +368,7 @@ module Upkeep
           target.target.id,
           target.identity_signature,
           target.sharing_signature,
+          target.deployment_signature,
           target.action,
           target.deoptimization_reason
         ]
@@ -349,6 +386,7 @@ module Upkeep
           existing.frame_id,
           existing.identity_signature,
           existing.sharing_signature,
+          existing.deployment_signature,
           existing.recipe,
           (existing.matched_dependency_keys + target.matched_dependency_keys).uniq,
           existing.action,

data/lib/upkeep/rails/cable/channel.rb

@@ -9,6 +9,17 @@ module Upkeep
       class Channel < ::ActionCable::Channel::Base
         SUBSCRIBE_NOTIFICATION = "subscribe_channel.upkeep"
 
+        # Liveness heartbeat: a connected page touches its subscription row on
+        # this interval, keeping updated_at fresh so opportunistic pruning only
+        # ever removes abandoned subscriptions. Invariant: connected =>
+        # touched at least every HEARTBEAT_INTERVAL => retained, so this must
+        # stay far below config.subscription_ttl (20 minutes vs a 24 hour
+        # default). It is a constant because ActionCable fixes periodic timer
+        # intervals at class load, before app configuration is readable.
+        HEARTBEAT_INTERVAL = 20 * 60
+
+        periodically :touch_upkeep_subscription, every: HEARTBEAT_INTERVAL
+
         def subscribed
           if ActiveSupport::Notifications.notifier.listening?(SUBSCRIBE_NOTIFICATION)
             instrumented_subscribe
@@ -25,6 +36,16 @@ module Upkeep
 
         private
 
+        # Cheap liveness touch (update_columns on the subscription row). Must
+        # never raise into the cable process; a missed heartbeat just leaves
+        # the subscription for a later beat or the opportunistic trim.
+        def touch_upkeep_subscription
+          Upkeep::Rails.subscriptions.touch(subscription_id)
+          nil
+        rescue StandardError
+          nil
+        end
+
         def instrumented_subscribe
           payload = { subscription_id: safe_subscription_id }
           ActiveSupport::Notifications.instrument(SUBSCRIBE_NOTIFICATION, payload) do
@@ -106,13 +127,14 @@ module Upkeep
         end
 
         def log_subscription_rejection(reason)
-          return unless reason == "missing_activation_token"
           return unless defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
 
-          ::Rails.logger.warn(
-            "[upkeep] subscription rejected: missing activation_token. " \
-            "If this started after upgrading upkeep-rails, refresh app/javascript/upkeep/subscription.js from the install generator."
-          )
+          message = +"[upkeep] subscription rejected (#{reason}) subscription_id=#{safe_subscription_id.inspect}."
+          if reason == "missing_activation_token"
+            message << " If this started after upgrading upkeep-rails, " \
+              "refresh app/javascript/upkeep/subscription.js from the install generator."
+          end
+          ::Rails.logger.warn(message)
         end
 
         def authorized_subscription?(subscription)

data/lib/upkeep/rails/cable/subscriber_identity.rb

@@ -41,8 +41,28 @@ module Upkeep
 
         attr_reader :action_cable_connection
 
+        # ActionCable::Connection::Base keeps `request` private on Rails
+        # 7.1-8.x but exposes `env` as a public attr_reader; the adapterized
+        # connection on Rails main exposes both publicly. Prefer a public
+        # `request`, otherwise build one from the public Rack env the same
+        # way Action Cable does. Never reach into private connection API.
         def action_cable_request
-          action_cable_connection.__send__(:request)
+          @action_cable_request ||=
+            if action_cable_connection.respond_to?(:request)
+              action_cable_connection.request
+            elsif action_cable_connection.respond_to?(:env)
+              ::ActionDispatch::Request.new(rails_rack_env)
+            else
+              raise UnidentifiedSubscriber,
+                "ActionCable connection exposes neither a public request nor a public env"
+            end
+        end
+
+        def rails_rack_env
+          env = action_cable_connection.env
+          return env unless defined?(::Rails.application) && ::Rails.application
+
+          ::Rails.application.env_config.merge(env)
         end
       end
 

data/lib/upkeep/rails/client_subscription.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "cgi"
-require "json"
 
 module Upkeep
   module Rails
@@ -16,20 +15,21 @@ module Upkeep
           "#{html}#{marker}"
       end
 
+      # The payload travels as attributes (like turbo-cable-stream-source), never
+      # as text content, so it can't show up as page text when JS is absent.
       def marker_for(identity:, subscription:)
-        payload = JSON.generate(
-          channel: CHANNEL,
-          subscription_id: subscription.id,
-          activation_token: ActivationToken.generate(subscription),
-          stream_name: identity.stream_name
-        ).gsub("</", '<\/')
-
-        id = "upkeep-subscription-source-#{subscription.id}"
+        attributes = {
+          "id" => "upkeep-subscription-source-#{subscription.id}",
+          "channel" => CHANNEL,
+          "subscription-id" => subscription.id,
+          "activation-token" => ActivationToken.generate(subscription),
+          "stream-name" => identity.stream_name
+        }
 
         [
-          %(<upkeep-subscription-source id="#{CGI.escapeHTML(id)}" ),
-          %(data-upkeep-subscription data-turbo-temporary>),
-          CGI.escapeHTML(payload),
+          %(<upkeep-subscription-source ),
+          attributes.map { |name, value| %(#{name}="#{CGI.escapeHTML(value.to_s)}") }.join(" "),
+          %( hidden style="display:none" data-upkeep-subscription data-turbo-temporary>),
           %(</upkeep-subscription-source>)
         ].join
       end

data/lib/upkeep/rails/cluster_guard.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Upkeep
+  module Rails
+    # Detects boot configurations where live updates silently break across
+    # cluster workers: an in-process cable adapter or an in-memory
+    # subscription store cannot reach browsers or subscriptions held by
+    # another process.
+    class ClusterGuard
+      IN_PROCESS_CABLE_ADAPTERS = %w[async].freeze
+
+      attr_reader :cable_adapter, :worker_count, :subscription_store, :environment
+
+      def initialize(cable_adapter:, worker_count:, subscription_store:, environment:)
+        @cable_adapter = cable_adapter.to_s
+        @worker_count = worker_count.to_i
+        @subscription_store = subscription_store&.to_sym
+        @environment = environment.to_s
+      end
+
+      def clustered?
+        worker_count.positive?
+      end
+
+      def problems
+        return [] unless clustered?
+
+        problems = []
+        if IN_PROCESS_CABLE_ADAPTERS.include?(cable_adapter)
+          problems << "the #{cable_adapter} Action Cable adapter is in-process, so broadcasts from one worker " \
+            "never reach sockets held by another; configure a cross-process cable adapter such as solid_cable " \
+            "or redis in config/cable.yml"
+        end
+        if subscription_store == :memory
+          problems << "subscription_store=:memory is per-process, so subscriptions registered in one worker are " \
+            "invisible to the others; set config.upkeep.subscription_store = :active_record"
+        end
+        problems
+      end
+
+      def error?
+        problems.any? && environment == "production"
+      end
+
+      def warning?
+        problems.any? && !error?
+      end
+
+      def message
+        return if problems.empty?
+
+        "Upkeep detected a clustered server (#{worker_count} workers) with a configuration that cannot " \
+          "deliver live updates across processes: #{problems.join("; ")}."
+      end
+    end
+  end
+end

data/lib/upkeep/rails/configuration.rb

@@ -8,7 +8,6 @@ module Upkeep
       SUBSCRIPTION_STORES = [:active_record, :memory].freeze
       REFUSED_BOUNDARY_BEHAVIORS = [:raise, :warn].freeze
       IDENTITY_SOURCES = [:current, :session, :cookie, :warden].freeze
-      DELIVERY_ADAPTERS = [:async, :active_job, :inline].freeze
 
       class IdentityDefinition
         attr_reader :name, :source, :source_key, :subscribe_block
@@ -99,18 +98,23 @@ module Upkeep
       attr_accessor :enabled
       attr_accessor :activation_token_expires_in
       attr_accessor :delivery_batch_window
-      attr_accessor :delivery_queue
+      # Seconds a subscription may go untouched before it counts as abandoned
+      # and becomes eligible for pruning. Connected pages are kept alive by the
+      # cable channel heartbeat, which fires far more often than this TTL.
+      attr_accessor :subscription_ttl
+      # Test/console hook: deliver changes synchronously in the caller instead
+      # of on the in-process background dispatcher.
+      attr_accessor :deliver_inline
       attr_reader :subscription_store
-      attr_reader :delivery_adapter
 
       def initialize
         @enabled = true
         @subscription_store = :active_record
-        @delivery_adapter = :async
-        @delivery_queue = :upkeep_realtime
+        @deliver_inline = false
         @delivery_batch_window = 0.01
         @refused_boundary_behavior = nil
         @activation_token_expires_in = 24 * 60 * 60
+        @subscription_ttl = 24 * 60 * 60
         @identity_definitions = {}
       end
 
@@ -125,17 +129,6 @@ module Upkeep
         @subscription_store = value
       end
 
-      def delivery_adapter=(value)
-        value = value.to_sym if value.respond_to?(:to_sym)
-
-        unless DELIVERY_ADAPTERS.include?(value)
-          raise ConfigurationError,
-            "Unknown Upkeep delivery_adapter #{value.inspect}; expected one of #{DELIVERY_ADAPTERS.join(", ")}"
-        end
-
-        @delivery_adapter = value
-      end
-
       def refused_boundary_behavior
         @refused_boundary_behavior || default_refused_boundary_behavior
       end

data/lib/upkeep/rails/controller_runtime.rb

@@ -87,6 +87,7 @@ module Upkeep
             end
           end
         end
+        changes = upkeep_stamp_change_request_id(changes)
         record_capture_payload(payload, capture) if capture
 
         measure_phase(payload, :deliver_changes_ms) do
@@ -118,6 +119,22 @@ module Upkeep
         result
       end
 
+      # Changes committed while handling this request carry the originating Turbo
+      # request id, so the client that caused them ignores its own refresh delivery
+      # (Turbo's recentRequests debounce). Breaks self-refresh loops from writes
+      # during GETs, e.g. view tracking.
+      def upkeep_stamp_change_request_id(changes)
+        request_id = upkeep_turbo_request_id
+        return changes unless request_id
+
+        changes.map { |change| change.respond_to?(:merge) ? change.merge(request_id: request_id) : change }
+      end
+
+      def upkeep_turbo_request_id
+        turbo_request_id = ::Turbo.current_request_id if defined?(::Turbo) && ::Turbo.respond_to?(:current_request_id)
+        turbo_request_id || request.headers["X-Turbo-Request-Id"]
+      end
+
       def record_capture_payload(payload, capture)
         payload[:response_status] = capture.response_status
         payload[:response_content_type] = capture.response_content_type

data/lib/upkeep/rails/railtie.rb

@@ -9,8 +9,7 @@ module Upkeep
         Upkeep::Rails.configure do |config|
           config.enabled = app.config.upkeep.fetch(:enabled, true)
           config.subscription_store = app.config.upkeep.fetch(:subscription_store, config.subscription_store)
-          config.delivery_adapter = app.config.upkeep.fetch(:delivery_adapter, Railtie.default_delivery_adapter(app))
-          config.delivery_queue = app.config.upkeep.fetch(:delivery_queue, config.delivery_queue)
+          config.deliver_inline = app.config.upkeep.fetch(:deliver_inline, config.deliver_inline)
           config.delivery_batch_window =
             app.config.upkeep.fetch(:delivery_batch_window, config.delivery_batch_window)
           config.activation_token_expires_in =
@@ -37,14 +36,6 @@ module Upkeep
           ::Rake.respond_to?(:application) &&
           ::Rake.application.top_level_tasks.any?
       end
-
-      def self.default_delivery_adapter(app)
-        if app.respond_to?(:env) && app.env.to_s == "production"
-          :active_job
-        else
-          Upkeep::Rails.configuration.delivery_adapter
-        end
-      end
     end
   end
 end

data/lib/upkeep/rails/testing.rb

@@ -14,7 +14,7 @@ module Upkeep
         # broadcast assertions.
         #
         # Production code should not call this; normal app delivery runs
-        # through the configured adapter.
+        # on the in-process dispatcher.
         #
         # @return [void]
         def drain_delivery!