upkeep-rails 0.1.9

data/lib/upkeep/rails/testing.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+module Upkeep
+  module Rails
+    # Test helpers for asserting the public Upkeep subscription lifecycle from
+    # Rails request, integration, and system tests.
+    module Testing
+      CHANGE_FACTS_THREAD_KEY = :upkeep_rails_testing_change_facts
+      @broadcast_capture_mutex = Mutex.new
+      @broadcast_captures = []
+
+      class << self
+        # Drains the async delivery dispatcher when a test needs deterministic
+        # broadcast assertions.
+        #
+        # Production code should not call this; normal app delivery runs
+        # through the configured adapter.
+        #
+        # @return [void]
+        def drain_delivery!
+          Upkeep::Rails.send(:drain_delivery_dispatcher!)
+        end
+
+        # Captures facts passed into Upkeep delivery while the block runs. This
+        # exposes the same committed-change payloads the planner sees, without
+        # broadcasting or altering application code.
+        #
+        # @return [Array(Object, Array<Hash>)] the block result and captured facts.
+        def capture_change_facts
+          previous = Thread.current[CHANGE_FACTS_THREAD_KEY]
+          facts = []
+          Thread.current[CHANGE_FACTS_THREAD_KEY] = facts
+
+          [yield, facts]
+        ensure
+          Thread.current[CHANGE_FACTS_THREAD_KEY] = previous
+        end
+
+        # Records delivery facts for capture_change_facts. Internal test hook;
+        # production delivery calls this only when a capture is active.
+        def record_change_facts(changes)
+          facts = Thread.current[CHANGE_FACTS_THREAD_KEY]
+          return unless facts
+
+          facts.concat(Array(changes).map { |change| clone_change_fact(change) })
+        end
+
+        # @return [Boolean] true when the current thread is capturing change facts.
+        def capturing_change_facts?
+          !!Thread.current[CHANGE_FACTS_THREAD_KEY]
+        end
+
+        # Captures rendered Upkeep delivery payloads while the block runs.
+        # This observes the batch after planning/rendering and before the
+        # app-specific transport adapter, so tests stay deterministic across
+        # ActionCable adapters.
+        def capture_broadcasts
+          broadcasts = []
+          broadcast_capture_mutex.synchronize { broadcast_captures << broadcasts }
+
+          yield
+          drain_delivery!
+          broadcasts.dup
+        ensure
+          broadcast_capture_mutex.synchronize { broadcast_captures.delete(broadcasts) } if broadcasts
+        end
+
+        # @return [Boolean] true when any thread is capturing delivery batches.
+        def capturing_broadcasts?
+          broadcast_capture_mutex.synchronize { broadcast_captures.any? }
+        end
+
+        # Records a rendered delivery batch for active capture_broadcasts
+        # blocks. Internal test hook; production delivery calls this only when
+        # a capture is active.
+        def record_delivery_batch(batch)
+          captures = broadcast_capture_mutex.synchronize { broadcast_captures.dup }
+          return if captures.empty?
+
+          bodies = batch.envelopes.map(&:body)
+          return if bodies.empty?
+
+          broadcast_capture_mutex.synchronize do
+            captures.each do |capture|
+              capture.concat(bodies) if broadcast_captures.include?(capture)
+            end
+          end
+        end
+
+        # Runs the invalidation planner against committed-change facts without
+        # enqueueing delivery or broadcasting.
+        #
+        # @param changes [Hash, Array<Hash>] one or more change facts.
+        # @param store [#reverse_index] subscription store to inspect.
+        # @return [Hash] concise planner match report.
+        def match_report(changes, store: Upkeep::Rails.subscriptions)
+          changes = changes.is_a?(Hash) ? [changes] : Array(changes)
+          lookup_payloads = []
+          subscription = ActiveSupport::Notifications.subscribe("lookup_subscription_index.upkeep") do |event|
+            lookup_payloads << event.payload.dup
+          end
+
+          plan = Upkeep::Invalidation::Planner.new(store: store).plan(changes)
+
+          {
+            candidate_entries: plan.candidate_entries.size,
+            matched_entries: plan.matched_entries.size,
+            miss_reason: match_miss_reason(plan, changes, lookup_payloads),
+            targets: plan.targets.map { |target| match_report_target(target) }
+          }
+        ensure
+          ActiveSupport::Notifications.unsubscribe(subscription) if subscription
+        end
+
+        private
+
+        attr_reader :broadcast_capture_mutex, :broadcast_captures
+
+        def clone_change_fact(change)
+          case change
+          when Hash
+            change.to_h.transform_values { |value| clone_change_fact(value) }
+          when Array
+            change.map { |value| clone_change_fact(value) }
+          else
+            begin
+              change.dup
+            rescue TypeError
+              change
+            end
+          end
+        end
+
+        def match_miss_reason(plan, changes, lookup_payloads)
+          return nil if plan.targets.any?
+          return "no_changes" if changes.empty?
+
+          lookup_payloads.reverse_each do |payload|
+            return payload.fetch(:miss_reason) if payload.key?(:miss_reason)
+          end
+
+          return "no_matching_subscriber" if plan.candidate_entries.empty?
+          return "dependencies_did_not_match_change" if plan.matched_entries.empty?
+
+          "no_renderable_target"
+        end
+
+        def match_report_target(target)
+          {
+            subscription_id: target.subscription_id,
+            subscriber_id: target.subscriber_id,
+            subscriber_ids: target.subscriber_ids,
+            target: {
+              kind: target.target.kind,
+              id: target.target.id,
+              reason: target.target.reason
+            },
+            shared_stream_target: {
+              kind: target.shared_stream_target.kind,
+              id: target.shared_stream_target.id
+            },
+            frame_id: target.frame_id,
+            identity_signature: target.identity_signature,
+            action: target.action,
+            matched_dependency_keys: target.matched_dependency_keys,
+            deoptimization_reason: target.deoptimization_reason
+          }
+        end
+      end
+
+      # Asserts that the last successful HTML response injected an Upkeep
+      # subscription marker and registered a subscription in the configured
+      # store.
+      #
+      # @param message [String, nil] optional assertion failure message.
+      # @return [void]
+      def assert_upkeep_subscription_registered(message = nil)
+        assert_select "upkeep-subscription-source[data-upkeep-subscription]"
+        assert Upkeep::Rails.subscriptions.subscriptions.any?,
+          message || "expected Upkeep to register at least one subscription"
+      end
+
+      # Returns the most recently registered Upkeep subscription.
+      #
+      # @return [Upkeep::Subscriptions::Subscription, nil]
+      def upkeep_subscription
+        Upkeep::Rails.subscriptions.subscriptions.last
+      end
+
+      # Returns every ActionCable stream name that can receive broadcasts for a
+      # subscription, including shared streams.
+      #
+      # @param subscription [Upkeep::Subscriptions::Subscription]
+      # @return [Array<String>]
+      # @raise [ArgumentError] when no subscription is registered.
+      def upkeep_stream_names(subscription = upkeep_subscription)
+        raise ArgumentError, "no Upkeep subscription is registered" unless subscription
+
+        ([subscription.metadata.fetch(:stream_name)] + subscription.metadata.fetch(:shared_stream_names, [])).uniq
+      end
+
+      # Activates the registered subscription so delivery lookup can find it.
+      #
+      # @param subscription [Upkeep::Subscriptions::Subscription]
+      # @return [Upkeep::Subscriptions::Subscription]
+      # @raise [ArgumentError] when no subscription is registered.
+      # @raise [Upkeep::Subscriptions::NotFound] when activation fails.
+      def activate_upkeep_subscription!(subscription = upkeep_subscription)
+        raise ArgumentError, "no Upkeep subscription is registered" unless subscription
+
+        activated = Upkeep::Rails.subscriptions.activate(subscription.id)
+        raise Upkeep::Subscriptions::NotFound, subscription.id unless activated
+
+        subscription
+      end
+
+      # Captures rendered Upkeep broadcasts while the block runs. This observes
+      # Upkeep after planning/rendering and before the application ActionCable
+      # adapter, so tests stay deterministic regardless of the host app's cable
+      # adapter.
+      #
+      # @param subscription [Upkeep::Subscriptions::Subscription]
+      # @return [Array<String>]
+      # @raise [ArgumentError] when called without a block or subscription.
+      def capture_upkeep_broadcasts(subscription = upkeep_subscription, &block)
+        raise ArgumentError, "capture_upkeep_broadcasts requires a block" unless block
+        raise ArgumentError, "no Upkeep subscription is registered" unless subscription
+
+        Upkeep::Rails::Testing.capture_broadcasts(&block)
+      end
+
+      # Drains async Upkeep delivery for deterministic test assertions.
+      #
+      # @return [void]
+      def drain_upkeep_delivery!
+        Upkeep::Rails::Testing.drain_delivery!
+      end
+
+      # Captures facts passed into Upkeep delivery while the block runs.
+      #
+      # @return [Array(Object, Array<Hash>)] the block result and captured facts.
+      def capture_upkeep_change_facts(&block)
+        raise ArgumentError, "capture_upkeep_change_facts requires a block" unless block
+
+        Upkeep::Rails::Testing.capture_change_facts(&block)
+      end
+
+      # Returns a dry-run invalidation planner report for one or more change
+      # facts against the configured Upkeep subscription store.
+      #
+      # @param changes [Hash, Array<Hash>] one or more change facts.
+      # @return [Hash]
+      def upkeep_match_report(changes)
+        Upkeep::Rails::Testing.match_report(changes)
+      end
+    end
+  end
+end

data/lib/upkeep/rails.rb

@@ -0,0 +1,370 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+require_relative "capture/request"
+require_relative "subscriptions/registrar"
+require_relative "rails/configuration"
+require_relative "rails/activation_token"
+require_relative "rails/delivery_job"
+require_relative "rails/replay"
+require_relative "rails/action_view_capture"
+require_relative "rails/cable"
+require_relative "rails/client_subscription"
+require_relative "rails/controller_runtime"
+require_relative "rails/install"
+require_relative "rails/testing"
+require_relative "rails/railtie" if defined?(::Rails::Railtie)
+
+module Upkeep
+  module Rails
+    SUBSCRIPTION_IDENTITY = "upkeep.subscription_identity"
+    REQUEST_CAPTURE = "request_capture.upkeep"
+    DELIVERY_ENQUEUE = "delivery_enqueue.upkeep"
+    DELIVERY_ENQUEUE_ERROR = "delivery_enqueue_error.upkeep"
+    INTERNAL_DELIVERY_TABLES = %w[
+      upkeep_subscriptions
+      upkeep_subscription_index_entries
+      upkeep_subscription_shape_index_entries
+    ].freeze
+
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield configuration
+      end
+
+      def subscriptions
+        discard_subscription_store! if @subscriptions && subscription_store_config_changed?
+        @subscriptions ||= build_subscription_store
+      end
+
+      def transport
+        @transport ||= Delivery::BroadcastTransport.new
+      end
+
+      def reset_runtime!
+        @delivery_dispatcher&.shutdown
+        @delivery_dispatcher = nil
+        @subscription_shape_cache&.reset
+        @subscription_registrar = nil
+        discard_subscription_store! if @subscriptions
+        @subscriptions = build_subscription_store
+        @subscriptions.reset
+        @transport = Delivery::BroadcastTransport.new
+      end
+
+      def register_controller_subscription(controller, capture)
+        recorder = capture.recorder
+        return unless subscription_response?(controller, capture)
+
+        decision = Cable::SubscriberIdentity.decision_for(controller.request, recorder: recorder)
+        unless recorder.reactive?
+          instrument_subscription_identity(
+            decision,
+            registered: false,
+            deopt_reason: "refused_boundary",
+            refused_boundaries: recorder.refused_boundaries.map(&:reason)
+          )
+          return
+        end
+
+        identity = Cable::SubscriberIdentity.derive_from_request(
+          controller.request,
+          recorder: recorder,
+          decision: decision
+        )
+        registration = subscription_registrar.register(
+          identity: identity,
+          decision: decision,
+          recorder: recorder,
+          signature: capture.signature,
+          metadata: identity_metadata(decision).merge(
+            path: controller.request.fullpath,
+            stream_name: identity.stream_name
+          )
+        )
+        instrument_subscription_identity(decision, registered: true, subscription: registration.subscription)
+
+        registration
+      rescue Cable::UnidentifiedSubscriber => error
+        instrument_subscription_identity(
+          decision || Cable::SubscriberIdentity.decision_for(controller.request, recorder: recorder),
+          registered: false,
+          deopt_reason: "unidentified_identity",
+          error: error.message
+        )
+        nil
+      end
+
+      # Dispatches committed application changes through the configured delivery
+      # adapter.
+      #
+      # ControllerRuntime calls this automatically after non-GET actions. Apps
+      # usually should not call it from controllers or models.
+      #
+      # @param changes [Array<#to_h>] change events to deliver. Defaults to the
+      #   current runtime change log.
+      # @return [Upkeep::Delivery::Transport::DispatchReport]
+      def deliver_changes!(changes = Runtime::ChangeLog.drain)
+        changes = deliverable_changes(changes)
+        record_testing_change_facts(changes)
+        return Delivery::Transport::DispatchReport.new([]) if changes.empty?
+
+        dispatch_changes(changes)
+      rescue StandardError => error
+        instrument_delivery_enqueue_error(changes, error)
+        Delivery::Transport::DispatchReport.new([])
+      end
+
+      # Delivers committed application changes immediately in the current
+      # process.
+      #
+      # This is used by the inline delivery adapter and Active Job worker. Tests
+      # that need deterministic async delivery should use
+      # Upkeep::Rails::Testing instead of calling this directly.
+      #
+      # @param changes [Array<#to_h>] change events to deliver. Defaults to the
+      #   current runtime change log.
+      # @return [Upkeep::Delivery::TurboStreams::Batch, Upkeep::Delivery::Transport::DispatchReport]
+      def deliver_changes_now!(changes = Runtime::ChangeLog.drain)
+        changes = deliverable_changes(changes)
+        record_testing_change_facts(changes)
+        return Delivery::Transport::DispatchReport.new([]) if changes.empty?
+
+        batch = delivery_batch_for([changes])
+        deliver_batch(batch)
+      end
+
+      def validate_configuration!(environment: rails_environment)
+        return true unless configuration.enabled
+
+        validate_subscription_store!(environment: environment)
+        true
+      end
+
+      private
+
+      def delivery_dispatcher
+        @delivery_dispatcher ||= Delivery::AsyncDispatcher.new(batch_window: configuration.delivery_batch_window) do |change_sets|
+          batch = delivery_batch_for(change_sets)
+          deliver_batch(batch)
+        end
+      end
+
+      def drain_delivery_dispatcher!
+        @delivery_dispatcher&.drain
+      end
+
+      def dispatch_changes(changes)
+        payload = {
+          adapter: configuration.delivery_adapter,
+          queue: configuration.delivery_queue,
+          change_count: changes.size
+        }
+
+        ActiveSupport::Notifications.instrument(DELIVERY_ENQUEUE, payload) do
+          case configuration.delivery_adapter
+          when :active_job
+            DeliveryJob.perform_later(changes)
+            Delivery::Transport::DispatchReport.new([])
+          when :async
+            delivery_dispatcher.enqueue(changes)
+          when :inline
+            deliver_changes_now!(changes)
+          end
+        end
+      end
+
+      def instrument_delivery_enqueue_error(changes, error)
+        ActiveSupport::Notifications.instrument(
+          DELIVERY_ENQUEUE_ERROR,
+          adapter: configuration.delivery_adapter,
+          queue: configuration.delivery_queue,
+          change_count: changes.size,
+          error_class: error.class.name,
+          error_message: error.message
+        )
+      end
+
+      def subscription_registrar
+        @subscription_registrar ||= Subscriptions::Registrar.new(
+          store: subscriptions,
+          shape_cache: subscription_shape_cache
+        )
+      end
+
+      def subscription_shape_cache
+        @subscription_shape_cache ||= Subscriptions::ShapeCache.new
+      end
+
+      def delivery_batch_for(change_sets)
+        change_sets = compact_change_sets(change_sets)
+        return Delivery::TurboStreams::Batch.new([]) if change_sets.empty?
+
+        planner = Invalidation::Planner.new(store: subscriptions)
+        plans = change_sets.map { |changes| planner.plan(changes) }
+        plans = plans.reject { |plan| plan.targets.empty? }
+        return Delivery::TurboStreams::Batch.new([]) if plans.empty?
+
+        Delivery::TurboStreams.new.build_many(plans)
+      end
+
+      def deliver_batch(batch)
+        record_testing_delivery_batch(batch)
+        transport.deliver(batch)
+      end
+
+      def compact_change_sets(change_sets)
+        change_sets
+          .map { |changes| deliverable_changes(changes) }
+          .reject(&:empty?)
+          .uniq { |changes| change_set_key(changes) }
+      end
+
+      def deliverable_changes(changes)
+        Array(changes).reject { |change| internal_delivery_change?(change) }
+      end
+
+      def record_testing_change_facts(changes)
+        return unless defined?(Testing) && Testing.respond_to?(:record_change_facts)
+        return if Testing.respond_to?(:capturing_change_facts?) && !Testing.capturing_change_facts?
+
+        Testing.record_change_facts(changes)
+      end
+
+      def record_testing_delivery_batch(batch)
+        return unless defined?(Testing) && Testing.respond_to?(:record_delivery_batch)
+        return if Testing.respond_to?(:capturing_broadcasts?) && !Testing.capturing_broadcasts?
+
+        Testing.record_delivery_batch(batch)
+      end
+
+      def internal_delivery_change?(change)
+        INTERNAL_DELIVERY_TABLES.include?(change_value(change, :table).to_s)
+      end
+
+      def change_set_key(changes)
+        changes.map { |change| change_key(change) }.sort
+      end
+
+      def change_key(change)
+        [
+          change_value(change, :type).to_s,
+          change_value(change, :table).to_s,
+          change_value(change, :model).to_s,
+          change_value(change, :id).to_s,
+          Array(change_value(change, :changed_attributes)).map(&:to_s).sort,
+          change_value(change, :old_values).inspect,
+          change_value(change, :new_values).inspect
+        ]
+      end
+
+      def change_value(change, key)
+        return unless change.respond_to?(:[])
+
+        change[key] || change[key.to_s]
+      end
+
+      def discard_subscription_store!
+        @subscriptions&.shutdown
+        @subscriptions = nil
+        @subscription_registrar = nil
+      end
+
+      def identity_metadata(decision)
+        {
+          identity_mode: decision.mode,
+          anonymous: decision.anonymous,
+          anonymous_deopt_reason: decision.deopt_reason,
+          identity_sources: decision.identity_sources,
+          identity_names: decision.identity_names
+        }.compact
+      end
+
+      def instrument_subscription_identity(decision, registered:, subscription: nil, deopt_reason: nil, **extra)
+        ActiveSupport::Notifications.instrument(
+          SUBSCRIPTION_IDENTITY,
+          {
+            registered: registered,
+            subscription_id: subscription&.id,
+            subscriber_id: subscription&.subscriber_id,
+            identity_mode: decision&.mode,
+            anonymous: decision&.anonymous,
+            anonymous_deopt_reason: deopt_reason || decision&.deopt_reason,
+            identity_sources: decision&.identity_sources,
+            identity_names: decision&.identity_names
+          }.merge(extra)
+        )
+      end
+
+      def subscription_response?(controller, capture)
+        controller.request.get? &&
+          capture.successful? &&
+          capture.html_response? &&
+          capture.html.include?("</") &&
+          capture.recorder.graph.frame_nodes.any?
+      end
+
+      def build_subscription_store
+        case configuration.subscription_store
+        when :active_record
+          schema_errors = Subscriptions::ActiveRecordStore.schema_errors(connect: true)
+          unless schema_errors.empty?
+            raise ConfigurationError,
+              active_record_subscription_store_error(schema_errors)
+          end
+
+          Subscriptions::ActiveRecordStore.new
+        when :memory
+          Subscriptions::Store.new
+        end.tap do
+          @subscription_store_name = configuration.subscription_store
+        end
+      end
+
+      def validate_subscription_store!(environment:)
+        if production_environment?(environment) && configuration.subscription_store == :memory
+          raise ConfigurationError,
+            "Upkeep subscription_store=:memory is only for development/test; production requires :active_record."
+        end
+
+        return true unless production_environment?(environment)
+        return true unless configuration.subscription_store == :active_record
+        schema_errors = Subscriptions::ActiveRecordStore.schema_errors(connect: true)
+        return true if schema_errors.empty?
+
+        raise ConfigurationError, active_record_subscription_store_error(schema_errors, production: true)
+      end
+
+      def active_record_subscription_store_error(schema_errors, production: false)
+        prefix = if production
+          "Upkeep production boot requires compatible upkeep_subscriptions, " \
+            "upkeep_subscription_index_entries, and upkeep_subscription_shape_index_entries tables " \
+            "for subscription_store=:active_record."
+        else
+          "Upkeep subscription_store=:active_record requires compatible upkeep_subscriptions, " \
+            "upkeep_subscription_index_entries, and upkeep_subscription_shape_index_entries tables."
+        end
+
+        "#{prefix} Schema errors: #{schema_errors.join("; ")}. Run bin/rails generate upkeep:install " \
+          "and bin/rails db:migrate, rebuild stale development/test databases, or set " \
+          "config.upkeep.subscription_store = :memory in development/test."
+      end
+
+      def production_environment?(environment)
+        environment.to_s == "production"
+      end
+
+      def rails_environment
+        ::Rails.env if defined?(::Rails) && ::Rails.respond_to?(:env)
+      end
+
+      def subscription_store_config_changed?
+        @subscription_store_name != configuration.subscription_store
+      end
+    end
+  end
+end