upkeep-rails 0.1.9

data/lib/upkeep/rails/configuration.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+module Upkeep
+  module Rails
+    class ConfigurationError < StandardError; end
+
+    class Configuration
+      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
+
+        def initialize(name:, source:, source_key:, subscribe_block:, absent_block: nil)
+          @name = name.to_sym
+          @source = source.to_sym
+          @source_key = source_key
+          @subscribe_block = subscribe_block
+          @absent_block = absent_block
+        end
+
+        def matches_dependency?(dependency)
+          case source
+          when :current
+            dependency.source == :current_attribute &&
+              metadata_value(dependency, :owner) == source_key.fetch(:owner) &&
+              metadata_value(dependency, :name) == source_key.fetch(:name)
+          when :session
+            dependency.source == :session && metadata_value(dependency, :key) == source_key
+          when :cookie
+            dependency.source == :cookie && metadata_value(dependency, :key) == source_key
+          when :warden
+            dependency.source == :warden_user && metadata_value(dependency, :scope) == source_key
+          else
+            false
+          end
+        end
+
+        def matches_source?(source, key)
+          source = source.to_sym
+
+          case self.source
+          when :current
+            source == :current &&
+              key.fetch(:owner).to_s == source_key.fetch(:owner) &&
+              key.fetch(:name).to_s == source_key.fetch(:name)
+          when :session, :cookie, :warden
+            source == self.source && key.to_s == source_key
+          else
+            false
+          end
+        end
+
+        def absent?(value)
+          return value.nil? unless @absent_block
+
+          @absent_block.arity == 1 ? @absent_block.call(value) : @absent_block.call
+        end
+
+        def absent_dependency?(dependency)
+          Upkeep::Dependencies.identity_absent_for?(dependency, name)
+        end
+
+        def source_label
+          case source
+          when :current
+            "#{source_key.fetch(:owner)}.#{source_key.fetch(:name)}"
+          when :session
+            "session[:#{source_key}]"
+          when :cookie
+            "cookies[:#{source_key}]"
+          when :warden
+            "warden.user(:#{source_key})"
+          end
+        end
+
+        private
+
+        def metadata_value(dependency, key)
+          value = dependency.metadata[key] || dependency.metadata[key.to_s]
+          value.to_s
+        end
+      end
+
+      class IdentityBuilder
+        attr_reader :subscribe_block, :absent_block
+
+        def absent_if(&block)
+          @absent_block = block
+        end
+
+        def subscribe(&block)
+          @subscribe_block = block
+        end
+      end
+
+      attr_accessor :enabled
+      attr_accessor :activation_token_expires_in
+      attr_accessor :delivery_batch_window
+      attr_accessor :delivery_queue
+      attr_reader :subscription_store
+      attr_reader :delivery_adapter
+
+      def initialize
+        @enabled = true
+        @subscription_store = :active_record
+        @delivery_adapter = :async
+        @delivery_queue = :upkeep_realtime
+        @delivery_batch_window = 0.01
+        @refused_boundary_behavior = nil
+        @activation_token_expires_in = 24 * 60 * 60
+        @identity_definitions = {}
+      end
+
+      def subscription_store=(value)
+        value = value.to_sym if value.respond_to?(:to_sym)
+
+        unless SUBSCRIPTION_STORES.include?(value)
+          raise ConfigurationError,
+            "Unknown Upkeep subscription_store #{value.inspect}; expected one of #{SUBSCRIPTION_STORES.join(", ")}"
+        end
+
+        @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
+
+      def refused_boundary_behavior=(value)
+        value = value.to_sym if value.respond_to?(:to_sym)
+
+        unless REFUSED_BOUNDARY_BEHAVIORS.include?(value)
+          raise ConfigurationError,
+            "Unknown Upkeep refused_boundary_behavior #{value.inspect}; expected one of #{REFUSED_BOUNDARY_BEHAVIORS.join(", ")}"
+        end
+
+        @refused_boundary_behavior = value
+      end
+
+      def identify(name, current: nil, session: nil, cookie: nil, warden: nil, &block)
+        source, source_key = identity_source(current: current, session: session, cookie: cookie, warden: warden)
+        builder = IdentityBuilder.new
+        if block
+          block.arity == 1 ? block.call(builder) : builder.instance_eval(&block)
+        end
+
+        unless builder.subscribe_block
+          raise ConfigurationError, "config.identify :#{name} requires a subscribe block"
+        end
+
+        @identity_definitions[name.to_sym] = IdentityDefinition.new(
+          name: name,
+          source: source,
+          source_key: source_key,
+          subscribe_block: builder.subscribe_block,
+          absent_block: builder.absent_block
+        )
+      end
+
+      def identity_presence_metadata(source:, key:, value:)
+        definitions = identity_definitions.select { |definition| definition.matches_source?(source, key) }
+        absent_by_name = definitions.to_h do |definition|
+          [definition.name.to_s, definition.absent?(value)]
+        end
+
+        {
+          partitioning: if definitions.any?
+            absent_by_name.values.any? { |absent| !absent }
+          else
+            !value.nil?
+          end,
+          absent_by_name: absent_by_name
+        }
+      end
+
+      def identity_definitions
+        @identity_definitions.values
+      end
+
+      def identity_definition(name)
+        @identity_definitions.fetch(name.to_sym)
+      end
+
+      def clear_identities!
+        @identity_definitions.clear
+      end
+
+      private
+
+      def identity_source(current:, session:, cookie:, warden:)
+        sources = {
+          current: current,
+          session: session,
+          cookie: cookie,
+          warden: warden
+        }.compact
+
+        unless sources.size == 1
+          raise ConfigurationError,
+            "config.identify requires exactly one source: #{IDENTITY_SOURCES.join(", ")}"
+        end
+
+        source, value = sources.first
+        [source, normalize_identity_source(source, value)]
+      end
+
+      def normalize_identity_source(source, value)
+        case source
+        when :current
+          owner, name = Array(value)
+          unless owner && name
+            raise ConfigurationError,
+              "config.identify current: expects [CurrentClass, :attribute]"
+          end
+
+          { owner: owner.to_s, name: name.to_s }
+        when :session, :cookie, :warden
+          value.to_s
+        end
+      end
+
+      def default_refused_boundary_behavior
+        if defined?(::Rails) && ::Rails.respond_to?(:env) && ::Rails.env.to_s == "production"
+          :warn
+        else
+          :raise
+        end
+      end
+    end
+  end
+end

data/lib/upkeep/rails/controller_runtime.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Upkeep
+  module Rails
+    module ControllerRuntime
+      extend ActiveSupport::Concern
+
+      SUPPRESS_KEY = :upkeep_rails_controller_runtime_suppressed
+
+      included do
+        prepend_around_action :upkeep_capture_request
+      end
+
+      # Public override point for host controllers. Return false to opt a request out
+      # of Upkeep capture and live registration: the action still runs and the page
+      # renders normally, but no subscription is recorded, no source is injected, and
+      # no boundary is analyzed (so an opaque relation on that request neither raises
+      # nor warns). Use for render paths Upkeep cannot prove and that should not be
+      # made reactive, e.g. full-text search results backed by raw tsvector SQL.
+      def upkeep_reactive_request?
+        true
+      end
+
+      module_function
+
+      def install
+        return if @installed
+        return unless defined?(::ActionController::Base)
+
+        ::ActionController::Base.include(self)
+        @installed = true
+      end
+
+      def installed?
+        !!@installed
+      end
+
+      def reset!
+        @installed = false
+      end
+
+      def suppress
+        previous = Thread.current[SUPPRESS_KEY]
+        Thread.current[SUPPRESS_KEY] = true
+        yield
+      ensure
+        Thread.current[SUPPRESS_KEY] = previous
+      end
+
+      def suppressed?
+        Thread.current[SUPPRESS_KEY]
+      end
+
+      private
+
+      def upkeep_capture_request(&action)
+        return action.call if ControllerRuntime.suppressed?
+        return action.call if Upkeep::Runtime::Observation.recorder
+
+        payload = {
+          controller: self.class.name,
+          action: action_name,
+          method: request.request_method,
+          path: request.fullpath,
+          subscription_request: upkeep_subscription_request?
+        }
+        ActiveSupport::Notifications.instrument(Upkeep::Rails::REQUEST_CAPTURE, payload) do
+          upkeep_capture_request_with_timing(action, payload)
+        end
+      end
+
+      def upkeep_capture_request_with_timing(action, payload)
+        measure_phase(payload, :deliver_pending_ms) { Upkeep::Rails.deliver_changes_now! }
+
+        result = nil
+        capture = nil
+        changes = []
+        measure_phase(payload, :change_capture_ms) do
+          _captured, changes = Upkeep::Runtime::ChangeLog.capture do
+            if payload.fetch(:subscription_request)
+              capture = Upkeep::Capture::Request.call(self, profile: request_capture_profile?) { action.call }
+              result = capture.action_result
+            else
+              measure_phase(payload, :action_ms) { result = action.call }
+            end
+          end
+        end
+        record_capture_payload(payload, capture) if capture
+
+        measure_phase(payload, :deliver_changes_ms) do
+          if capture
+            Upkeep::Rails.deliver_changes_now!(changes)
+          else
+            Upkeep::Rails.deliver_changes!(changes)
+          end
+        end
+
+        registration = nil
+        if capture
+          measure_phase(payload, :register_ms) do
+            registration = Upkeep::Rails.register_controller_subscription(self, capture)
+          end
+        end
+        payload[:registered] = !!registration
+        if capture && registration
+          measure_phase(payload, :inject_ms) do
+            response.body = Upkeep::Rails::ClientSubscription.inject(
+              capture.html,
+              identity: registration.identity,
+              subscription: registration.subscription
+            )
+          end
+          payload[:subscription_id] = registration.subscription.id
+        end
+
+        result
+      end
+
+      def record_capture_payload(payload, capture)
+        payload[:response_status] = capture.response_status
+        payload[:response_content_type] = capture.response_content_type
+        payload[:response_media_type] = capture.response_media_type
+        payload[:html_response] = capture.html_response?
+        payload[:response_successful] = capture.successful?
+        payload[:html_bytes] = capture.html.bytesize
+        payload[:graph_frames] = capture.recorder.graph.frame_nodes.size
+        payload[:graph_dependencies] = capture.recorder.graph.dependency_nodes.size
+        capture.timings.each do |phase, ms|
+          payload[:"capture_#{phase}"] = ms
+        end
+        capture.counters.each do |counter, value|
+          payload[:"capture_#{counter}"] = value
+        end
+      end
+
+      def measure_phase(payload, key)
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        yield
+      ensure
+        payload[key] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000.0).round(3)
+      end
+
+      def upkeep_subscription_request?
+        upkeep_reactive_request? && (request.get? || request.head?)
+      end
+
+      def request_capture_profile?
+        ActiveSupport::Notifications.notifier.listening?(Upkeep::Rails::REQUEST_CAPTURE)
+      end
+    end
+  end
+end

data/lib/upkeep/rails/delivery_job.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "active_job"
+
+module Upkeep
+  module Rails
+    class DeliveryJob < ::ActiveJob::Base
+      queue_as { Upkeep::Rails.configuration.delivery_queue }
+
+      def perform(changes)
+        Upkeep::Rails.deliver_changes_now!(normalize_changes(changes))
+      end
+
+      private
+
+      def normalize_changes(changes)
+        Array(changes).map { |change| normalize_change(change) }
+      end
+
+      def normalize_change(change)
+        return change unless change.respond_to?(:to_h)
+
+        change.to_h.transform_keys do |key|
+          key.respond_to?(:to_sym) ? key.to_sym : key
+        end
+      end
+    end
+  end
+end

data/lib/upkeep/rails/install.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Upkeep
+  module Rails
+    module Install
+      module_function
+
+      def call
+        return unless Upkeep::Rails.configuration.enabled
+        return if @installed
+
+        Runtime::Install.call if defined?(::ActiveRecord::Base)
+        ActionViewCapture.install if defined?(::ActionView::Template)
+        ControllerRuntime.install if defined?(::ActionController::Base)
+
+        @installed = true
+      end
+
+      def installed?
+        !!@installed
+      end
+
+      def reset!
+        @installed = false
+      end
+    end
+  end
+end

data/lib/upkeep/rails/railtie.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Upkeep
+  module Rails
+    class Railtie < ::Rails::Railtie
+      config.upkeep = ActiveSupport::OrderedOptions.new
+
+      initializer "upkeep_rails.configure" do |app|
+        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.delivery_batch_window =
+            app.config.upkeep.fetch(:delivery_batch_window, config.delivery_batch_window)
+          config.activation_token_expires_in =
+            app.config.upkeep.fetch(:activation_token_expires_in, config.activation_token_expires_in)
+          config.refused_boundary_behavior =
+            app.config.upkeep.fetch(:refused_boundary_behavior, config.refused_boundary_behavior)
+        end
+      end
+
+      initializer "upkeep_rails.install" do
+        ActiveSupport.on_load(:active_record) { Upkeep::Rails::Install.call }
+        ActiveSupport.on_load(:action_controller_base) { Upkeep::Rails::Install.call }
+        ActiveSupport.on_load(:action_view) { Upkeep::Rails::Install.call }
+      end
+
+      initializer "upkeep_rails.validate_configuration", after: "upkeep_rails.install" do |app|
+        app.config.after_initialize do
+          Upkeep::Rails.validate_configuration! unless Railtie.rake_task?
+        end
+      end
+
+      def self.rake_task?
+        defined?(::Rake) &&
+          ::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/replay.rb

@@ -0,0 +1,197 @@
+# 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)
+        template_context = replay_template_context
+        renderer_for(replay).render(
+          template: replay.template,
+          locals: revive_hash(replay.locals, template: template_context),
+          assigns: revive_hash(replay.assigns, template: template_context)
+        )
+      end
+
+      def render_fragment(replay)
+        template_context = replay_template_context
+        renderer_for(replay).render(
+          partial: partial_path(replay.template),
+          locals: revive_hash(replay.locals, template: template_context),
+          assigns: revive_hash(replay.assigns, template: template_context)
+        )
+      end
+
+      def render_collection(replay)
+        template_context = replay_template_context
+        options = revive_hash(replay.options, template: template_context)
+        collection = revive_value(replay.collection, template: template_context)
+
+        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)
+        template_context = replay_template_context
+        options = revive_hash(replay.options, template: template_context)
+        record = revive_value(replay.record, template: template_context)
+        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, template: replay_template_context)
+        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, template: template)
+        end
+      end
+
+      def revive_value(snapshot, template: replay_template_context)
+        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, template: template) }
+        when ::Upkeep::Replay::HashValue
+          revive_hash(snapshot.entries, template: template)
+        when ::Upkeep::Replay::LiteralValue
+          snapshot.value
+        when ::Upkeep::Replay::RailsFormBuilderValue
+          revive_form_builder(snapshot, template: template)
+        else
+          raise "unsupported Rails replay value type: #{snapshot.class.name}"
+        end
+      end
+
+      def revive_form_builder(snapshot, template:)
+        constantize(snapshot.builder_class).new(
+          snapshot.object_name,
+          revive_value(snapshot.object, template: template),
+          template,
+          revive_hash(snapshot.options, template: template)
+        )
+      end
+
+      def replay_template_context
+        ::ActionView::Base.empty
+      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