upkeep-rails 0.1.0

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "action_cable"
+require "active_support/notifications"
+
+module Upkeep
+  module Rails
+    module Cable
+      class Channel < ::ActionCable::Channel::Base
+        SUBSCRIBE_NOTIFICATION = "subscribe_channel.upkeep"
+
+        def subscribed
+          if ActiveSupport::Notifications.notifier.listening?(SUBSCRIBE_NOTIFICATION)
+            instrumented_subscribe
+          else
+            subscribe_without_instrumentation
+          end
+        end
+
+        def unsubscribed
+          Upkeep::Rails.subscriptions.unregister(subscription_id)
+        rescue KeyError, ActiveRecord::RecordNotFound
+          nil
+        end
+
+        private
+
+        def instrumented_subscribe
+          payload = { subscription_id: safe_subscription_id }
+          ActiveSupport::Notifications.instrument(SUBSCRIBE_NOTIFICATION, payload) do
+            subscribe_without_instrumentation(payload: payload)
+          end
+        end
+
+        def subscribe_without_instrumentation(payload: nil)
+          id = subscription_id
+          payload[:subscription_id] = id if payload
+          subscription = measure(payload, :fetch_ms) { Upkeep::Rails.subscriptions.fetch(id) }
+          authorized = measure(payload, :authorization_ms) { authorized_subscription?(subscription) }
+          unless authorized
+            payload[:rejected] = true if payload
+            return reject
+          end
+
+          measure(payload, :activation_ms) { Upkeep::Rails.subscriptions.activate(id) }
+          stream_count = measure(payload, :stream_attach_ms) { attach_streams(subscription) }
+          payload[:stream_count] = stream_count if payload
+        rescue KeyError, ActiveRecord::RecordNotFound, UnidentifiedSubscriber
+          payload[:rejected] = true if payload
+          reject
+        end
+
+        def attach_streams(subscription)
+          stream_from stream_name_for(subscription)
+          count = 1
+          shared_stream_names_for(subscription).each do |stream_name|
+            stream_from stream_name
+            count += 1
+          end
+          count
+        end
+
+        def measure(payload, key)
+          return yield unless payload
+
+          started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          yield
+        ensure
+          payload[key] = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000.0).round(3) if payload && started_at
+        end
+
+        def safe_subscription_id
+          subscription_id
+        rescue KeyError
+          nil
+        end
+
+        def subscription_id
+          params.fetch(:subscription_id)
+        end
+
+        def authorized_subscription?(subscription)
+          return true if anonymous_public_subscription?(subscription)
+          return true unless metadata_value(subscription, :identity_mode)
+
+          SubscriberIdentity.derive_all(connection)
+            .any? { |identity| identity.subscriber_id == subscription.subscriber_id }
+        end
+
+        def anonymous_public_subscription?(subscription)
+          metadata_value(subscription, :identity_mode) == SubscriberIdentity::ANONYMOUS_PUBLIC_MODE
+        end
+
+        def stream_name_for(subscription)
+          metadata_value(subscription, :stream_name) || subscription.metadata.fetch(:stream_name)
+        end
+
+        def shared_stream_names_for(subscription)
+          metadata_value(subscription, :shared_stream_names) || []
+        end
+
+        def metadata_value(subscription, key)
+          subscription.metadata[key] || subscription.metadata[key.to_s]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "securerandom"
+
+module Upkeep
+  module Rails
+    module Cable
+      class UnidentifiedSubscriber < StandardError; end
+
+      Identity = Data.define(:subscriber_id, :stream_name, :components)
+      Decision = Data.define(:mode, :anonymous, :deopt_reason, :identity_sources)
+
+      module SubscriberIdentity
+        ANONYMOUS_PUBLIC_MODE = "anonymous_public"
+        IDENTIFIED_MODE = "identified"
+        CONNECTION_IDENTITY_SOURCES = %w[Current.user cookie current_attribute session warden_user].freeze
+
+        module_function
+
+        def derive(connection)
+          derive_all(connection).last
+        end
+
+        def derive_all(connection)
+          identities = []
+          request_components = request_components(connection.request) if connection.respond_to?(:request)
+          identifier_components = identifier_components(connection)
+
+          identities << for_components(request_components) if request_components&.any?
+          identities << for_components(Array(request_components) + identifier_components) if identifier_components.any?
+          identities = identities.uniq(&:subscriber_id)
+
+          raise UnidentifiedSubscriber, "ActionCable connection has no server identifiers" if identities.empty?
+
+          identities
+        end
+
+        def derive_from_request(request, recorder:, decision: decision_for(request, recorder: recorder))
+          components = if decision.anonymous
+            anonymous_components
+          else
+            request_components(request) + recorder_components(recorder)
+          end
+
+          if components.empty?
+            raise UnidentifiedSubscriber,
+              "subscription has identity dependencies but no canonical request or recorder identity"
+          end
+
+          for_components(components)
+        end
+
+        def decision_for(_request = nil, recorder:)
+          dependencies = identity_dependencies(recorder)
+          if dependencies.empty?
+            Decision.new(ANONYMOUS_PUBLIC_MODE, true, nil, [])
+          else
+            Decision.new(
+              IDENTIFIED_MODE,
+              false,
+              "identity_dependencies_present",
+              dependencies.map { |dependency| dependency.source.to_s }.uniq.sort
+            )
+          end
+        end
+
+        def identifier_components(connection)
+          identifiers = Array(connection.identifiers)
+          identifiers.map { |name| component_for(name, connection.public_send(name)) }
+        end
+
+        def request_components(request)
+          session_id = session_id_for(request)
+          return [] unless session_id
+
+          [scalar_component(:rails_session, session_id)]
+        end
+
+        def for_identifiers(identifiers)
+          for_components(identifiers.map { |name, value| component_for(name, value) })
+        end
+
+        def for_components(components)
+          canonical_bytes = JSON.generate(components.sort_by { |component| component.fetch(:name) })
+          subscriber_id = "action_cable:#{Digest::SHA256.hexdigest(canonical_bytes)}"
+
+          Identity.new(
+            subscriber_id,
+            Delivery::ActionCableAdapter.stream_name_for(subscriber_id),
+            components
+          )
+        end
+
+        def recorder_components(recorder)
+          identity_dependencies(recorder)
+            .filter_map { |dependency| component_for_dependency(dependency) }
+            .uniq
+        end
+
+        def anonymous_components
+          [ scalar_component(:anonymous_public_subscription, SecureRandom.uuid) ]
+        end
+
+        def identity_dependencies(recorder)
+          return [] unless recorder
+
+          recorder.graph.dependency_nodes
+            .map(&:payload)
+            .select(&:identity?)
+            .select { |dependency| connection_identity_dependency?(dependency) }
+            .uniq(&:cache_key)
+        end
+
+        def connection_identity_dependency?(dependency)
+          CONNECTION_IDENTITY_SOURCES.include?(dependency.source.to_s)
+        end
+
+        def component_for_dependency(dependency)
+          if dependency.source == :current_attribute && current_user_dependency?(dependency)
+            model_component(:current_user, dependency.key.fetch(:value))
+          elsif dependency.source == "Current.user"
+            model_component(:current_user, dependency.metadata)
+          elsif dependency.source == :warden_user
+            model_component(:"warden_#{dependency.metadata.fetch(:scope)}", dependency.key.fetch(:value))
+          end
+        end
+
+        def current_user_dependency?(dependency)
+          dependency.metadata.fetch(:name) == "user"
+        end
+
+        def model_component(name, identity)
+          return unless identity.is_a?(Hash) && identity[:model] && identity[:id]
+
+          {
+            name: name.to_s,
+            kind: "model",
+            model: identity.fetch(:model),
+            id: identity.fetch(:id).to_s
+          }
+        end
+
+        def component_for(name, value)
+          raise UnidentifiedSubscriber, "ActionCable identifier #{name} is nil" if value.nil?
+
+          if active_record?(value)
+            active_record_component(name, value)
+          elsif scalar?(value)
+            scalar_component(name, value)
+          elsif value.respond_to?(:to_gid_param)
+            global_id_component(name, value)
+          else
+            raise UnidentifiedSubscriber, "ActionCable identifier #{name} has no canonical identity"
+          end
+        end
+
+        def active_record?(value)
+          defined?(::ActiveRecord::Base) && value.is_a?(::ActiveRecord::Base)
+        end
+
+        def active_record_component(name, record)
+          raise UnidentifiedSubscriber, "ActionCable identifier #{name} is an unsaved record" unless record.id
+
+          model_component(name, model: record.class.name, id: record.id)
+        end
+
+        def scalar?(value)
+          value.is_a?(String) ||
+            value.is_a?(Symbol) ||
+            value.is_a?(Integer) ||
+            value == true ||
+            value == false
+        end
+
+        def scalar_component(name, value)
+          {
+            name: name.to_s,
+            kind: "scalar",
+            class: value.class.name,
+            value: value.to_s
+          }
+        end
+
+        def global_id_component(name, value)
+          {
+            name: name.to_s,
+            kind: "global_id",
+            value: value.to_gid_param
+          }
+        end
+
+        def session_id_for(request)
+          return unless request&.respond_to?(:session)
+
+          session = request.session
+          session_id = session.id if session.respond_to?(:id)
+          session_id = session_id.public_id if session_id.respond_to?(:public_id)
+          session_id = session_id.private_id if session_id.respond_to?(:private_id)
+          session_id = session[:session_id] if blank?(session_id) && session.respond_to?(:[])
+
+          session_id.to_s unless blank?(session_id)
+        rescue StandardError
+          nil
+        end
+
+        def blank?(value)
+          value.nil? || value == ""
+        end
+      end
+    end
+  end
+end

data/lib/upkeep/rails/cable.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "cable/subscriber_identity"
+require_relative "cable/channel"

data/lib/upkeep/rails/client_subscription.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Upkeep
+  module Rails
+    module ClientSubscription
+      CHANNEL = "Upkeep::Rails::Cable::Channel"
+
+      module_function
+
+      def inject(html, identity:, subscription:)
+        marker = marker_for(identity: identity, subscription: subscription)
+        insert_before_closing("head", html, marker) ||
+          insert_before_closing("body", html, marker) ||
+          "#{html}#{marker}"
+      end
+
+      def marker_for(identity:, subscription:)
+        payload = JSON.generate(
+          channel: CHANNEL,
+          subscription_id: subscription.id,
+          stream_name: identity.stream_name
+        ).gsub("</", '<\/')
+
+        %(<script type="application/json" data-upkeep-subscription>#{payload}</script>)
+      end
+
+      def insert_before_closing(tag, html, marker)
+        index = html.rindex(%(</#{tag}>)) || html.rindex(%(</#{tag.upcase}>))
+        return unless index
+
+        "#{html[0...index]}#{marker}#{html[index..]}"
+      end
+    end
+  end
+end

data/lib/upkeep/rails/configuration.rb

@@ -0,0 +1,57 @@
+# 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
+
+      attr_accessor :enabled
+      attr_reader :subscription_store
+
+      def initialize
+        @enabled = true
+        @subscription_store = :active_record
+        @refused_boundary_behavior = nil
+      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 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
+
+      private
+
+      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,137 @@
+# 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
+
+      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
+
+        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
+        measure_phase(payload, :deliver_changes_ms) { Upkeep::Rails.deliver_changes!(changes) }
+
+        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?
+        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/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,36 @@
+# 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.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
+    end
+  end
+end