upkeep-rails 0.1.0

data/lib/upkeep/rails/replay.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "action_controller"
+require "active_support/hash_with_indifferent_access"
+require "stringio"
+
+module Upkeep
+  module Rails
+    module Replay
+      module_function
+
+      class RackSession < ActiveSupport::HashWithIndifferentAccess
+        def enabled? = true
+
+        def loaded? = true
+
+        def id = self[:session_id]
+
+        def id_was = id
+      end
+
+      def render(recipe)
+        replay = recipe.replay
+
+        case replay
+        when ::Upkeep::Replay::ControllerPage
+          render_controller_page(replay)
+        when ::Upkeep::Replay::Template
+          render_template(replay)
+        when ::Upkeep::Replay::Fragment
+          render_fragment(replay)
+        when ::Upkeep::Replay::Collection
+          render_collection(replay)
+        when ::Upkeep::Replay::CollectionMember
+          render_collection_member(replay)
+        else
+          raise "unknown Rails replay recipe type: #{replay.class.name}"
+        end
+      end
+
+      def render_controller_page(replay)
+        controller = constantize(replay.controller_class)
+        _status, _headers, body = ControllerRuntime.suppress do
+          controller.action(replay.action).call(rack_env(replay.env))
+        end
+        collect_response_body(body)
+      end
+
+      def render_template(replay)
+        renderer_for(replay).render(
+          template: replay.template,
+          locals: revive_hash(replay.locals)
+        )
+      end
+
+      def render_fragment(replay)
+        renderer_for(replay).render(
+          partial: partial_path(replay.template),
+          locals: revive_hash(replay.locals)
+        )
+      end
+
+      def render_collection(replay)
+        options = revive_hash(replay.options)
+        collection = revive_value(replay.collection)
+
+        if replay.derived_partial?
+          renderer_for(replay).render(collection)
+        else
+          renderer_for(replay).render(options.merge(
+            partial: replay.partial,
+            collection: collection
+          ))
+        end
+      end
+
+      def render_collection_member(replay)
+        options = revive_hash(replay.options)
+        record = revive_value(replay.record)
+        locals = options.fetch(:locals, {})
+        local_name = (options[:as] || inferred_local_name(replay.partial)).to_sym
+
+        renderer_for(replay).render(
+          partial: replay.partial,
+          locals: locals.merge(local_name => record)
+        )
+      end
+
+      def renderer_for(replay)
+        if replay.controller_class
+          constantize(replay.controller_class).renderer
+        else
+          ::ActionController::Base.renderer
+        end
+      end
+
+      def rack_env(env)
+        env = env.each_with_object({}) { |(key, value), copy| copy[key.to_s] = revive_env_value(value) }
+        env["rack.input"] = StringIO.new
+        env["rack.errors"] ||= StringIO.new
+        env
+      end
+
+      def revive_hash(values)
+        values = values.entries if values.is_a?(::Upkeep::Replay::HashValue)
+
+        values.each_with_object({}) do |(key, value), revived|
+          revived[key.to_sym] = revive_value(value)
+        end
+      end
+
+      def revive_value(snapshot)
+        snapshot = ::Upkeep::Replay.value(snapshot)
+
+        case snapshot
+        when ::Upkeep::Replay::ActiveRecordValue
+          constantize(snapshot.model).find(snapshot.id)
+        when ::Upkeep::Replay::ActiveRecordRelationValue
+          constantize(snapshot.model).find_by_sql(snapshot.sql)
+        when ::Upkeep::Replay::ArrayValue
+          snapshot.items.map { |item| revive_value(item) }
+        when ::Upkeep::Replay::HashValue
+          revive_hash(snapshot.entries)
+        when ::Upkeep::Replay::LiteralValue
+          snapshot.value
+        else
+          raise "unsupported Rails replay value type: #{snapshot.class.name}"
+        end
+      end
+
+      def revive_env_value(value)
+        return revive_replay_session(value) if replay_session_snapshot?(value)
+
+        case value
+        when Hash
+          value.transform_values { |nested_value| revive_env_value(nested_value) }
+        when Array
+          value.map { |nested_value| revive_env_value(nested_value) }
+        else
+          value
+        end
+      end
+
+      def replay_session_snapshot?(value)
+        return false unless value.is_a?(Hash)
+
+        type = value["__upkeep_replay_type"] || value[:__upkeep_replay_type]
+        type == "rack_session"
+      end
+
+      def revive_replay_session(snapshot)
+        values = snapshot["values"] || snapshot[:values] || {}
+        RackSession.new(revive_env_value(values))
+      end
+
+      def partial_path(template)
+        template.to_s.sub(%r{(^|/)_([^/]+)\z}, "\\1\\2")
+      end
+
+      def inferred_local_name(partial)
+        File.basename(partial.to_s).sub(/\A_/, "").to_sym
+      end
+
+      def constantize(name)
+        name.to_s.split("::").reduce(Object) { |namespace, constant_name| namespace.const_get(constant_name) }
+      end
+
+      def collect_response_body(body)
+        body.each.to_a.join
+      ensure
+        body.close if body.respond_to?(:close)
+      end
+
+    end
+  end
+end

data/lib/upkeep/rails/testing.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Upkeep
+  module Rails
+    module Testing
+      def assert_upkeep_subscription_registered(message = nil)
+        assert_select "script[data-upkeep-subscription]"
+        assert Upkeep::Rails.subscriptions.subscriptions.any?,
+          message || "expected Upkeep to register at least one subscription"
+      end
+
+      def upkeep_subscription
+        Upkeep::Rails.subscriptions.subscriptions.last
+      end
+
+      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
+
+      def capture_upkeep_broadcasts(subscription = upkeep_subscription, &block)
+        raise ArgumentError, "capture_upkeep_broadcasts requires a block" unless block
+        raise NoMethodError, "include ActionCable::TestHelper before calling capture_upkeep_broadcasts" unless respond_to?(:capture_broadcasts)
+
+        captures = {}
+        nested = upkeep_stream_names(subscription).reverse_each.reduce(block) do |inner, stream_name|
+          proc { captures[stream_name] = capture_broadcasts(stream_name, &inner) }
+        end
+
+        nested.call
+        captures.values.flatten
+      end
+    end
+  end
+end

data/lib/upkeep/rails.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+require_relative "capture/request"
+require_relative "subscriptions/registrar"
+require_relative "rails/configuration"
+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"
+    INTERNAL_DELIVERY_TABLES = %w[
+      upkeep_subscriptions
+      upkeep_subscription_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
+
+      def deliver_changes!(changes = Runtime::ChangeLog.drain)
+        changes = deliverable_changes(changes)
+        return Delivery::Transport::DispatchReport.new([]) if changes.empty?
+
+        delivery_dispatcher.enqueue(changes)
+      end
+
+      def deliver_changes_now!(changes = Runtime::ChangeLog.drain)
+        changes = deliverable_changes(changes)
+        return Delivery::Transport::DispatchReport.new([]) if changes.empty?
+
+        batch = delivery_batch_for([changes])
+        transport.deliver(batch)
+      end
+
+      def drain_delivery!
+        @delivery_dispatcher&.drain
+      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 do |change_sets|
+          batch = delivery_batch_for(change_sets)
+          transport.deliver(batch)
+        end
+      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 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 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
+        }.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
+          }.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
+          unless Subscriptions::ActiveRecordStore.available?(connect: true)
+            raise ConfigurationError,
+              "Upkeep subscription_store=:active_record requires the upkeep_subscriptions and " \
+              "upkeep_subscription_index_entries tables. Run bin/rails generate upkeep:install " \
+              "and bin/rails db:migrate, or set config.upkeep.subscription_store = :memory in development/test."
+          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
+        return true if Subscriptions::ActiveRecordStore.available?(connect: true)
+
+        raise ConfigurationError,
+          "Upkeep production boot requires the upkeep_subscriptions and " \
+          "upkeep_subscription_index_entries tables for subscription_store=:active_record."
+      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