rails_pulse 0.3.3 → 0.4.0.pre.2

data/lib/rails_pulse/cleanup_service.rb

@@ -41,12 +41,16 @@ module RailsPulse
       RailsPulse.logger.info "Time-based cleanup: removing records older than #{cutoff_time}"
 
       # Clean up in order that respects foreign key constraints
-      @stats[:time_based][:operations] = cleanup_operations_by_time(cutoff_time)
-      @stats[:time_based][:job_runs]   = cleanup_job_runs_by_time(cutoff_time)
-      @stats[:time_based][:requests]   = cleanup_requests_by_time(cutoff_time)
-      @stats[:time_based][:queries]    = cleanup_queries_by_time(cutoff_time)
-      @stats[:time_based][:routes]     = cleanup_routes_by_time(cutoff_time)
-      @stats[:time_based][:jobs]       = cleanup_jobs_by_time(cutoff_time)
+      @stats[:time_based][:operations]            = cleanup_operations_by_time(cutoff_time)
+      @stats[:time_based][:job_runs]              = cleanup_job_runs_by_time(cutoff_time)
+      @stats[:time_based][:requests]              = cleanup_requests_by_time(cutoff_time)
+      @stats[:time_based][:queries]               = cleanup_queries_by_time(cutoff_time)
+      @stats[:time_based][:routes]                = cleanup_routes_by_time(cutoff_time)
+      @stats[:time_based][:jobs]                  = cleanup_jobs_by_time(cutoff_time)
+      if exception_tables_exist?
+        @stats[:time_based][:exception_occurrences] = cleanup_exception_occurrences_by_time(cutoff_time)
+        @stats[:time_based][:exception_groups]      = cleanup_orphaned_exception_groups
+      end
     end
 
     def perform_count_based_cleanup
@@ -63,12 +67,32 @@ module RailsPulse
       ops_scope = cutoff ? RailsPulse::Operation.where("occurred_at < ?", cutoff) : RailsPulse::Operation.none
 
       # Clean up in order that respects foreign key constraints
-      @stats[:count_based][:operations] = cleanup_by_count(RailsPulse::Operation, :rails_pulse_operations, order_column: :occurred_at, scope: ops_scope)
-      @stats[:count_based][:job_runs]   = cleanup_job_runs_by_count
-      @stats[:count_based][:requests]   = cleanup_requests_by_count
-      @stats[:count_based][:queries]    = cleanup_queries_by_count
-      @stats[:count_based][:routes]     = cleanup_routes_by_count
-      @stats[:count_based][:jobs]       = cleanup_jobs_by_count
+      @stats[:count_based][:operations]            = cleanup_by_count(RailsPulse::Operation, :rails_pulse_operations, order_column: :occurred_at, scope: ops_scope)
+      @stats[:count_based][:job_runs]              = cleanup_job_runs_by_count
+      @stats[:count_based][:requests]              = cleanup_requests_by_count
+      @stats[:count_based][:queries]               = cleanup_queries_by_count
+      @stats[:count_based][:routes]                = cleanup_routes_by_count
+      @stats[:count_based][:jobs]                  = cleanup_jobs_by_count
+      if exception_tables_exist?
+        @stats[:count_based][:exception_occurrences] = cleanup_exception_occurrences_by_count
+        @stats[:count_based][:exception_groups]      = cleanup_exception_groups_by_count
+        @stats[:count_based][:orphaned_exception_groups] = cleanup_orphaned_exception_groups
+      end
+      if deployments_table_exists?
+        @stats[:count_based][:deployments] = cleanup_deployments_by_count
+      end
+    end
+
+    # Deployments are markers, not measurements, so they are never pruned by
+    # age — a marker from before the retention window still explains a
+    # summary row. They are capped by count so the token-authenticated
+    # create endpoint cannot grow the table without bound.
+    def cleanup_deployments_by_count
+      cleanup_by_count(RailsPulse::Deployment, :rails_pulse_deployments, order_column: :started_at)
+    end
+
+    def deployments_table_exists?
+      RailsPulse::ApplicationRecord.connection.table_exists?(:rails_pulse_deployments)
     end
 
     # Shared helper: delete oldest records beyond a configured max count
@@ -188,10 +212,81 @@ module RailsPulse
       cleanup_by_count(RailsPulse::Job, :rails_pulse_jobs, order_column: :created_at, scope: scope)
     end
 
+    def exception_tables_exist?
+      connection = RailsPulse::ApplicationRecord.connection
+      connection.table_exists?(:rails_pulse_exception_groups) &&
+        connection.table_exists?(:rails_pulse_exception_occurrences)
+    end
+
+    def cleanup_exception_occurrences_by_time(cutoff_time)
+      exception_occurrences_cleanup_scope.where("occurred_at < ?", cutoff_time).delete_all
+    end
+
+    def cleanup_exception_occurrences_by_count
+      cleanup_by_count(
+        RailsPulse::ExceptionOccurrence,
+        :rails_pulse_exception_occurrences,
+        order_column: :occurred_at,
+        scope: exception_occurrences_cleanup_scope
+      )
+    end
+
+    # Preserve exempts a group from all automatic cleanup, including its
+    # occurrence rows — otherwise a preserved group can lose its backtraces.
+    def exception_occurrences_cleanup_scope
+      preserved_ids = RailsPulse::ExceptionGroup.where(preserve: true).select(:id)
+      RailsPulse::ExceptionOccurrence.where.not(exception_group_id: preserved_ids)
+    end
+
+    # Prune oldest non-preserved, non-ignored groups when over the configured cap.
+    # Child occurrences must be deleted first — there is no ON DELETE CASCADE on the FK.
+    def cleanup_exception_groups_by_count
+      max_records = @config.max_table_records[:rails_pulse_exception_groups]
+      return 0 unless max_records
+
+      current_count = RailsPulse::ExceptionGroup.count
+      return 0 if current_count <= max_records
+
+      overage = current_count - max_records
+      scope = RailsPulse::ExceptionGroup.where(preserve: false).where.not(status: "ignored")
+      # Only delete as many as the deletable population allows — if ignored/preserved
+      # groups dominate, we delete what we can and log when the cap cannot be met.
+      deletable_count = scope.count
+      records_to_delete = [ overage, deletable_count ].min
+      return 0 if records_to_delete <= 0
+
+      ids_to_delete = scope.order(last_seen_at: :asc).limit(records_to_delete).pluck(:id)
+      return 0 if ids_to_delete.empty?
+
+      RailsPulse::ExceptionOccurrence.where(exception_group_id: ids_to_delete).delete_all
+      RailsPulse::ExceptionGroup.where(id: ids_to_delete).delete_all
+
+      if overage > deletable_count
+        RailsPulse.logger.warn("[RailsPulse] Exception group cap #{max_records} cannot be met: " \
+          "#{current_count - ids_to_delete.size} remain (#{current_count - deletable_count} are preserved/ignored)")
+      end
+
+      ids_to_delete.size
+    end
+
+    # Delete groups whose last occurrence was removed — uses an atomic subquery
+    # so no orphan can be deleted while a concurrent occurrence is being inserted.
+    # preserve: true and ignored groups are never deleted automatically.
+    def cleanup_orphaned_exception_groups
+      RailsPulse::ExceptionGroup
+        .where(preserve: false)
+        .where.not(status: "ignored")
+        .where("id NOT IN (SELECT DISTINCT exception_group_id FROM rails_pulse_exception_occurrences)")
+        .delete_all
+    end
+
     def perform_summary_cleanup
-      # Hourly summaries are only used for the 1-day time range view — anything
-      # older than 2 days is unreachable in the UI and safe to delete.
-      cutoff = 2.days.ago
+      # Hourly summaries back the 1-day time range view and set how precisely
+      # Operations::ChangePoint can place a change. Beyond this cutoff the finest
+      # answer available is a day, so raising `hourly_summary_retention` is what
+      # buys hour-accurate change points further back — at the cost of summary
+      # table growth. Day, week and month summaries are never pruned.
+      cutoff = @config.hourly_summary_retention.ago
       deleted = RailsPulse::Summary.where(period_type: "hour").where("period_start < ?", cutoff).delete_all
       @stats[:time_based][:hourly_summaries] = deleted
     end

data/lib/rails_pulse/configuration.rb

@@ -9,14 +9,18 @@ module RailsPulse
                   :ignored_queues,
                   :track_assets,
                   :track_jobs,
+                  :track_exceptions,
+                  :capture_exception_params,
+                  :exception_message_filter,
+                  :capture_actual_sql,
                   :custom_asset_patterns,
                   :mount_path,
                   :full_retention_period,
                   :archiving_enabled,
-                  :max_table_records,
                   :connects_to,
                   :authentication_enabled,
                   :authentication_method,
+                  :authorize,
                   :authentication_redirect_path,
                   :tags,
                   :job_tracking_mode,
@@ -27,7 +31,10 @@ module RailsPulse
                   :async,
                   :service_level_objectives,
                   :query_service_level_objectives,
-                  :warn_on_stale_summaries
+                  :warn_on_stale_summaries,
+                  :baseline_window,
+                  :comparison_window,
+                  :hourly_summary_retention
 
     # Override the attr_accessor setter to track explicit assignment.
     # The default (enabled in production) should not trigger a warning
@@ -42,7 +49,10 @@ module RailsPulse
     attr_reader :route_thresholds,
                 :request_thresholds,
                 :query_thresholds,
-                :job_thresholds
+                :job_thresholds,
+                :exception_thresholds,
+                :max_table_records,
+                :regression_thresholds
 
     def initialize
       @enabled = true
@@ -50,6 +60,9 @@ module RailsPulse
       @request_thresholds = { slow: 700, very_slow: 2000, critical: 4000 }
       @query_thresholds = { slow: 100, very_slow: 500, critical: 1000 }
       @job_thresholds = { slow: 5_000, very_slow: 30_000, critical: 60_000 }
+      # Exception thresholds are occurrence counts over the dashboard period,
+      # not durations — an exception has no duration.
+      @exception_thresholds = { warning: 10, critical: 100 }
       @ignored_routes = []
       @ignored_requests = []
       @ignored_queries = []
@@ -57,6 +70,18 @@ module RailsPulse
       @ignored_queues = []
       @track_assets = false
       @track_jobs = false
+      # Off unless the host initializer opts in. The install template sets true
+      # for new apps; existing 0.3.3 initializers omit this key, so a true
+      # default would start capturing exception messages (unfiltered) on upgrade.
+      @track_exceptions = false
+      @capture_exception_params = true
+      # Optional host hook applied to every captured exception message after
+      # the built-in filter_parameters redaction. nil means no extra filtering.
+      @exception_message_filter = nil
+      # Off by default — actual_sql contains unparameterized SQL on mysql2
+      # (prepared_statements: false) and PG behind PgBouncer transaction mode.
+      # Inline literals (emails, passwords) would be stored in plaintext.
+      @capture_actual_sql = false
       @custom_asset_patterns = []
       @mount_path = nil
       @full_retention_period = 30.days
@@ -67,12 +92,18 @@ module RailsPulse
         rails_pulse_job_runs: 50_000,
         rails_pulse_queries: 10_000,
         rails_pulse_routes: 1_000,
-        rails_pulse_jobs: 1_000
+        rails_pulse_jobs: 1_000,
+        rails_pulse_exception_occurrences: 50_000,
+        rails_pulse_exception_groups: 10_000,
+        rails_pulse_deployments: 1_000
       }
       @connects_to = nil
-      @authentication_enabled = Rails.env.production?
+      @authentication_enabled = !(Rails.env.development? || Rails.env.test?)
       @authentication_enabled_explicitly_set = false
       @authentication_method = nil
+      # Fail-closed predicate: ->(controller) { true to allow }. Anything
+      # falsy is a 403. Runs after authentication_method, if both are set.
+      @authorize = nil
       @authentication_redirect_path = "/"
       @tags = [ "ignored", "critical", "experimental" ]
       @job_tracking_mode = :universal
@@ -99,6 +130,29 @@ module RailsPulse
       # Show a warning banner when summaries haven't been generated recently
       @warn_on_stale_summaries = true
 
+      # Historical comparison. The baseline is the traffic-weighted metric across
+      # `baseline_window` of day summaries; `comparison_window` is the recent
+      # slice measured against it.
+      @baseline_window   = 28.days
+      @comparison_window = 1.day
+
+      # Hourly summaries are what give a change point its precision. They are
+      # pruned aggressively because the 1-day UI view is all that reads them, so
+      # raising this is the knob that buys hour-accurate change points further
+      # back, at the cost of summary-table growth.
+      @hourly_summary_retention = 2.days
+
+      # Deterministic regression rules. A change must clear both the ratio and
+      # the absolute floor: without the floor, 2ms to 4ms reports as a 100%
+      # regression. min_samples keeps low-traffic routes from generating noise.
+      @regression_thresholds = {
+        ratio:                1.5,
+        min_delta_ms:         50.0,
+        min_delta_rate:       1.0,
+        min_samples:          100,
+        min_baseline_periods: 3
+      }
+
       # Validate defaults eagerly so that a misconfigured initializer raises at
       # boot time rather than at the first request. Auth settings are not
       # validated against defaults — only when the user explicitly enables
@@ -128,6 +182,15 @@ module RailsPulse
       @job_thresholds = value
     end
 
+    # Merge user-supplied caps into the defaults so tables added in newer
+    # versions still have a cap when the user carries an older explicit hash.
+    # A nil value explicitly disables count-based cleanup.
+    def max_table_records=(value)
+      return @max_table_records = nil if value.nil?
+
+      @max_table_records = (@max_table_records || {}).merge(value)
+    end
+
     # Get all routes to ignore, including asset patterns if track_assets is false
     def ignored_routes
       routes = @ignored_routes.dup
@@ -151,8 +214,10 @@ module RailsPulse
       validate_job_settings!
       validate_dashboard_settings!
       validate_tracking_settings!
+      validate_exception_settings!
       validate_service_level_objectives_settings!
       validate_query_service_level_objectives_settings!
+      validate_comparison_settings!
     end
 
     private
@@ -174,6 +239,7 @@ module RailsPulse
       validate_threshold_hash!(@request_thresholds, "request_thresholds")
       validate_threshold_hash!(@query_thresholds, "query_thresholds")
       validate_threshold_hash!(@job_thresholds, "job_thresholds")
+      validate_threshold_hash!(@exception_thresholds, "exception_thresholds")
     end
 
     def validate_retention_settings!
@@ -188,6 +254,41 @@ module RailsPulse
       end
     end
 
+    def validate_comparison_settings!
+      {
+        baseline_window:          @baseline_window,
+        comparison_window:        @comparison_window,
+        hourly_summary_retention: @hourly_summary_retention
+      }.each do |name, value|
+        unless value.respond_to?(:seconds) && value.to_i > 0
+          raise ArgumentError, "#{name} must be a positive time duration (e.g., 7.days), got #{value.inspect}"
+        end
+      end
+
+      if @baseline_window.to_i <= @comparison_window.to_i
+        raise ArgumentError,
+          "baseline_window (#{@baseline_window.inspect}) must be longer than " \
+          "comparison_window (#{@comparison_window.inspect})"
+      end
+
+      unless @regression_thresholds.is_a?(Hash)
+        raise ArgumentError, "regression_thresholds must be a hash, got #{@regression_thresholds.class}"
+      end
+
+      %i[ratio min_delta_ms min_delta_rate min_samples min_baseline_periods].each do |key|
+        value = @regression_thresholds[key]
+        unless value.is_a?(Numeric) && value > 0
+          raise ArgumentError, "regression_thresholds[:#{key}] must be a positive number, got #{value.inspect}"
+        end
+      end
+
+      if @regression_thresholds[:ratio] <= 1
+        raise ArgumentError,
+          "regression_thresholds[:ratio] must be greater than 1 — it is a multiple of the baseline, " \
+          "got #{@regression_thresholds[:ratio].inspect}"
+      end
+    end
+
     def validate_patterns!
       [ @ignored_routes, @ignored_requests, @ignored_queries, @custom_asset_patterns ].each do |patterns|
         patterns.each do |pattern|
@@ -214,13 +315,17 @@ module RailsPulse
     end
 
     def validate_authentication_settings!
-      if @authentication_enabled && @authentication_enabled_explicitly_set && @authentication_method.nil?
+      if @authentication_enabled && @authentication_enabled_explicitly_set && @authentication_method.nil? && @authorize.nil?
         RailsPulse.logger.warn "Authentication is enabled but no authentication method is configured. This will deny all access."
       end
 
       if @authentication_method && ![ Proc, Symbol, String ].include?(@authentication_method.class)
         raise ArgumentError, "authentication_method must be a Proc, Symbol, String, or nil, got #{@authentication_method.class}"
       end
+
+      if @authorize && !@authorize.respond_to?(:call)
+        raise ArgumentError, "authorize must respond to #call (a proc or lambda receiving the controller and returning true to allow), got #{@authorize.class}"
+      end
     end
 
     def validate_tags!
@@ -273,6 +378,20 @@ module RailsPulse
       end
     end
 
+    def validate_exception_settings!
+      unless [ true, false ].include?(@track_exceptions)
+        raise ArgumentError, "track_exceptions must be a boolean"
+      end
+
+      unless [ true, false ].include?(@capture_exception_params)
+        raise ArgumentError, "capture_exception_params must be a boolean"
+      end
+
+      if @exception_message_filter && !@exception_message_filter.respond_to?(:call)
+        raise ArgumentError, "exception_message_filter must respond to #call (a proc or lambda taking the message and the exception), got #{@exception_message_filter.class}"
+      end
+    end
+
     def validate_service_level_objectives_settings!
       unless @service_level_objectives.is_a?(Array)
         raise ArgumentError, "service_level_objectives must be an array, got #{@service_level_objectives.class}"

data/lib/rails_pulse/engine.rb

@@ -1,8 +1,10 @@
 require "rails_pulse/version"
 require "rails_pulse/statistics"
+require "rails_pulse/route_indexes"
 require "rails_pulse/middleware/request_collector"
 require "rails_pulse/middleware/asset_server"
 require "rails_pulse/subscribers/operation_subscriber"
+require "rails_pulse/subscribers/exception_subscriber"
 require "rails_pulse/job_run_collector"
 require "rails_pulse/active_job_extensions"
 require "rails_pulse/extensions/active_record"
@@ -16,7 +18,27 @@ module RailsPulse
   autoload :SummaryService, File.expand_path("../../app/services/rails_pulse/summary_service", __dir__)
   autoload :QueryAnalysisService, File.expand_path("../../app/services/rails_pulse/query_analysis_service", __dir__)
   autoload :TagFilterService, File.expand_path("../../app/services/rails_pulse/tag_filter_service", __dir__)
+  autoload :ExceptionCaptureService, File.expand_path("../../app/services/rails_pulse/exception_capture_service", __dir__)
+  autoload :ExceptionMessageSanitizer, File.expand_path("../../app/services/rails_pulse/exception_message_sanitizer", __dir__)
   autoload :OperationSuggestions, File.expand_path("../../app/services/rails_pulse/operation_suggestions", __dir__)
+  autoload :RoutePathNormalizer,             File.expand_path("../../app/services/rails_pulse/route_path_normalizer", __dir__)
+  autoload :RouteRecognizer,                 File.expand_path("../../app/services/rails_pulse/route_recognizer", __dir__)
+  autoload :RouteMerger,                     File.expand_path("../../app/services/rails_pulse/route_merger", __dir__)
+  autoload :RouteMigrator,                   File.expand_path("../../app/services/rails_pulse/route_migrator", __dir__)
+  autoload :RouteControllerActionBackfiller, File.expand_path("../../app/services/rails_pulse/route_controller_action_backfiller", __dir__)
+
+  # Historical comparison operations. This namespace is the read-only interface
+  # for "what changed?" — everything else in the codebase, and anything built on
+  # top of Rails Pulse later, should ask these rather than querying summaries
+  # directly.
+  module Operations
+    autoload :ChangePoint, File.expand_path("../../app/services/rails_pulse/operations/change_point", __dir__)
+    autoload :Compare,     File.expand_path("../../app/services/rails_pulse/operations/compare", __dir__)
+    autoload :Comparison,  File.expand_path("../../app/services/rails_pulse/operations/comparison", __dir__)
+    autoload :Metric,      File.expand_path("../../app/services/rails_pulse/operations/metric", __dir__)
+    autoload :Series,      File.expand_path("../../app/services/rails_pulse/operations/series", __dir__)
+    autoload :Subject,     File.expand_path("../../app/services/rails_pulse/operations/subject", __dir__)
+  end
 
   # Analysis services
   module Analysis
@@ -33,6 +55,7 @@ module RailsPulse
   module Installers
     autoload :MigrationInstaller, File.expand_path("installers/migration_installer", __dir__)
     autoload :ConfigInstaller, File.expand_path("installers/config_installer", __dir__)
+    autoload :ConfigUpdater, File.expand_path("installers/config_updater", __dir__)
   end
 
   # Stats reporting services
@@ -64,24 +87,12 @@ module RailsPulse
     end
 
     initializer "rails_pulse.assets" do |app|
-      # Register Rails Pulse assets with Sprockets for production/CDN deployment
-      if app.config.respond_to?(:assets)
-        # Add vendor assets to the asset pipeline
-        app.config.assets.paths << Engine.root.join("vendor", "assets", "stylesheets").to_s
-        app.config.assets.paths << Engine.root.join("vendor", "assets", "javascripts").to_s
-
-        # Register bundled assets for precompilation
-        if defined?(::Sprockets)
-          app.config.assets.precompile += %w[
-            rails-pulse.css
-            rails-pulse.js
-            rails-pulse-icons.js
-          ]
-        end
-      end
+      next unless RailsPulse.configuration.mount_dashboard
 
-      # Fallback: Add middleware for development/non-CDN setups
-      # This serves assets directly when not using precompiled manifest
+      # Dashboard assets are bundled at gem build time. They are not registered
+      # with Sprockets (re-minifying the 2 MB bundle OOMs small hosts — #190).
+      # assets:precompile copies them into public/assets for CDN/CSP; the
+      # middleware is the development / no-pipeline fallback.
       assets_path = Engine.root.join("public")
       app.middleware.insert_after Rack::Runtime, RailsPulse::Middleware::AssetServer,
         assets_path.to_s,
@@ -99,6 +110,10 @@ module RailsPulse
       RailsPulse::Subscribers::OperationSubscriber.subscribe!
     end
 
+    initializer "rails_pulse.exception_notifications" do
+      RailsPulse::Subscribers::ExceptionSubscriber.subscribe!
+    end
+
     initializer "rails_pulse.active_job" do
       ActiveSupport.on_load(:active_job) do
         include RailsPulse::ActiveJobExtensions

data/lib/rails_pulse/installers/config_updater.rb

@@ -0,0 +1,202 @@
+module RailsPulse
+  module Installers
+    # Inserts settings from the install template that the host initializer does
+    # not already mention. Existing lines are never rewritten, so `git diff` is
+    # the review: keep or discard hunks. Values that differ between a new
+    # install and an upgrade (today: track_exceptions) use the gem default.
+    class ConfigUpdater
+      ASSIGNMENT = /\A\s*(#\s*)?config\.(\w+)\s*=/.freeze
+      HASH_ENTRY = /\A\s*([a-z_][a-z0-9_]*):/.freeze
+
+      UPGRADE_VALUE_OVERRIDES = {
+        "track_exceptions" => "false"
+      }.freeze
+
+      BANNER = <<~RUBY.gsub(/^/, "  ")
+        # ====================================================================================================
+        #                              ADDED BY rails generate rails_pulse:upgrade
+        # ====================================================================================================
+        # New settings from this gem version. Existing values above were not changed.
+        # Review with git diff and keep or discard hunks as you like.
+
+      RUBY
+
+      attr_reader :output, :source, :destination
+
+      def self.update(destination:, source: nil, output: $stdout)
+        new(destination: destination, source: source, output: output).update
+      end
+
+      def self.template_path
+        File.expand_path("../../../../lib/generators/rails_pulse/templates/rails_pulse.rb", __FILE__)
+      end
+
+      def initialize(destination:, source: nil, output: $stdout)
+        @destination = destination
+        @source = source || self.class.template_path
+        @output = output
+      end
+
+      def update
+        return { status: :missing, keys: [], hash_keys: [] } unless File.exist?(destination)
+
+        host = File.read(destination)
+        missing_keys = template_settings.map { |setting| setting[:key] } - mentioned_keys(host)
+        hash_keys = missing_hash_entries(host, missing_keys)
+
+        return { status: :unchanged, keys: [], hash_keys: [] } if missing_keys.empty? && hash_keys.empty?
+
+        updated = host
+        updated = inject_hash_entries(updated, hash_keys) if hash_keys.any?
+        updated = append_settings(updated, missing_keys) if missing_keys.any?
+        File.write(destination, updated)
+
+        { status: :updated, keys: missing_keys, hash_keys: hash_keys.map { |entry| entry[:name] } }
+      end
+
+      private
+
+      def template_settings
+        @template_settings ||= parse_settings(File.read(source))
+      end
+
+      def parse_settings(content)
+        settings = []
+        comments = []
+        lines = content.lines
+        index = 0
+
+        while index < lines.size
+          line = lines[index]
+
+          if line.match?(ASSIGNMENT)
+            key = line[ASSIGNMENT, 2]
+            assignment, index = read_multiline(lines, index)
+            unless settings.any? { |setting| setting[:key] == key }
+              settings << { key: key, lines: comments + assignment }
+            end
+            comments = []
+          elsif preamble?(line)
+            comments = []
+            index += 1
+          else
+            comments << line
+            index += 1
+          end
+        end
+
+        settings
+      end
+
+      def preamble?(line)
+        line.match?(/\A\s*(RailsPulse\.configure|end)\b/) || line.match?(/\A\s*do\s*\|config\|/)
+      end
+
+      def read_multiline(lines, index)
+        collected = [ lines[index] ]
+        depth = nest_delta(lines[index])
+        index += 1
+
+        while index < lines.size && depth.positive?
+          collected << lines[index]
+          depth += nest_delta(lines[index])
+          index += 1
+        end
+
+        [ collected, index ]
+      end
+
+      def nest_delta(line)
+        code = line.sub(/#.*\z/, "")
+        code.count("{") - code.count("}") + code.count("[") - code.count("]")
+      end
+
+      def mentioned_keys(content)
+        content.scan(/config\.(\w+)/).flatten.uniq
+      end
+
+      def missing_hash_entries(host, missing_keys)
+        template_settings.filter_map do |setting|
+          next if missing_keys.include?(setting[:key])
+          next unless host.match?(/^\s*config\.#{Regexp.escape(setting[:key])}\s*=\s*\{/)
+
+          setting[:lines].filter_map do |line|
+            name = line[HASH_ENTRY, 1]
+            next unless name
+            next if host.match?(/^\s*#{Regexp.escape(name)}:/)
+
+            { setting: setting[:key], name: name, line: line }
+          end
+        end.flatten
+      end
+
+      def inject_hash_entries(content, entries)
+        entries.group_by { |entry| entry[:setting] }.reduce(content) do |text, (setting, grouped)|
+          pattern = /(^\s*config\.#{Regexp.escape(setting)}\s*=\s*\{)(.*?)(\n\s*\})/m
+          text.sub(pattern) do
+            opening, body, closing = Regexp.last_match[1], Regexp.last_match[2], Regexp.last_match[3]
+            "#{opening}#{body_with_comma(body)}\n#{grouped.map { |entry| entry[:line].rstrip }.join("\n")}#{closing}"
+          end
+        end
+      end
+
+      def body_with_comma(body)
+        lines = body.lines
+        index = lines.rindex { |line| line.strip != "" }
+        return body unless index
+
+        working = lines[index].chomp
+        return body if working.match?(/,\s*(#.*)?\z/)
+
+        working = if working.include?("#")
+          working.sub(/\s+#/, ", #")
+        else
+          "#{working},"
+        end
+        lines[index] = "#{working}\n"
+        lines.join
+      end
+
+      def append_settings(content, keys)
+        blocks = keys.filter_map do |key|
+          setting = template_settings.find { |candidate| candidate[:key] == key }
+          next unless setting
+
+          apply_overrides(setting[:lines], key).join
+        end
+        return content if blocks.empty?
+
+        insertion = BANNER + blocks.join("\n").gsub(/\n+\z/, "\n")
+        insert_before_configure_end(content, insertion)
+      end
+
+      def insert_before_configure_end(content, insertion)
+        lines = content.lines
+        start_index = lines.index { |line| line.match?(/^\s*RailsPulse\.configure\b/) }
+
+        unless start_index
+          return content + "\nRailsPulse.configure do |config|\n#{insertion}end\n"
+        end
+
+        indent = lines[start_index][/\A\s*/]
+        end_index = ((start_index + 1)...lines.size).find do |index|
+          lines[index].match?(/\A#{Regexp.escape(indent)}end\b/)
+        end
+
+        unless end_index
+          return content.sub(/\nend\s*\z/, "\n\n#{insertion}end\n")
+        end
+
+        (lines[0...end_index] + [ "\n#{insertion}" ] + lines[end_index..]).join
+      end
+
+      def apply_overrides(lines, key)
+        return lines unless UPGRADE_VALUE_OVERRIDES.key?(key)
+
+        lines.map do |line|
+          line.sub(/config\.#{Regexp.escape(key)}\s*=\s*.*/, "config.#{key} = #{UPGRADE_VALUE_OVERRIDES[key]}")
+        end
+      end
+    end
+  end
+end