rails-profiler 0.40.0 → 0.42.0

data/app/controllers/profiler/api/compare_controller.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Profiler
+  module Api
+    class CompareController < ApplicationController
+      skip_before_action :verify_authenticity_token
+
+      # Only the node names of config.peers are read from the request; a URL is never accepted.
+      def show
+        token_a = params[:a]
+        token_b = params[:b]
+
+        errors = []
+        errors << "Missing parameter: a" unless token_a.present?
+        errors << "Missing parameter: b" unless token_b.present?
+
+        if errors.any?
+          render json: { errors: errors }, status: :unprocessable_entity and return
+        end
+
+        node_a = params[:node_a].to_s
+        node_b = params[:node_b].to_s
+        if token_a == token_b && node_a == node_b
+          render json: { errors: ["Cannot compare a profile with itself"] }, status: :unprocessable_entity and return
+        end
+
+        render json: ProfileComparison.call(token_a.to_s, token_b.to_s, node_a: node_a, node_b: node_b)
+      rescue ProfileComparison::NotFound => e
+        render json: { errors: e.message.split("\n") }, status: :not_found
+      rescue Profiler::Error => e
+        render json: { errors: [e.message] }, status: :bad_gateway
+      end
+
+      # The nodes a profile can be read from: this instance, then the names of config.peers.
+      def nodes
+        render json: { nodes: [Peers::LOCAL_NODE] + Peers.names }
+      rescue Profiler::Error => e
+        render json: { errors: [e.message] }, status: :unprocessable_entity
+      end
+    end
+  end
+end

data/app/controllers/profiler/api/config_controller.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Profiler
+  module Api
+    # Read-only: the settings the file:line links need, for the dashboard and for the browser
+    # extension, which falls back on them when it has none of its own.
+    class ConfigController < ApplicationController
+      def show
+        config = Profiler.configuration
+        render json: {
+          editor_url_scheme: config.editor_link_scheme,
+          editor_path_map: config.editor_path_map
+        }
+      end
+    end
+  end
+end

data/app/controllers/profiler/application_controller.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../../../lib/profiler/cluster/security"
+require_relative "../../../lib/profiler/peers"
 
 module Profiler
   class ApplicationController < ActionController::Base
@@ -23,6 +24,7 @@ module Profiler
     def authorize_request
       # Checked first, so that :allow_local does not log a refusal for the master's calls.
       return if cluster_master_request?
+      return if peer_read_request?
       return if Profiler.configuration.authorized?(request)
 
       deny("Not authorized to access the profiler")
@@ -47,6 +49,13 @@ module Profiler
       Profiler.configuration.slave? && Cluster::Security.request_secret_valid?(request)
     end
 
+    # Another instance reading one profile to compare it with its own (Profiler::Peers). The
+    # shared peer_token opens exactly one door: GET of a single profile, nothing else.
+    def peer_read_request?
+      request.get? && controller_path == "profiler/api/profiles" && action_name == "show" &&
+        Peers.request_token_valid?(request)
+    end
+
     def handle_unverified_request
       deny("Missing #{Profiler::FORGERY_PROTECTION_HEADER} header or CSRF token")
     end

data/app/controllers/profiler/compare_controller.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Profiler
+  class CompareController < ApplicationController
+    def show
+      @token_a = params[:a]
+      @token_b = params[:b]
+      @node_a = params[:node_a].to_s
+      @node_b = params[:node_b].to_s
+
+      redirect_to root_path unless @token_a.present? && @token_b.present?
+    end
+  end
+end

data/app/views/profiler/compare/show.html.erb

@@ -0,0 +1,6 @@
+<div id="profiler-compare"
+     data-token-a="<%= @token_a %>"
+     data-token-b="<%= @token_b %>"
+     data-node-a="<%= @node_a %>"
+     data-node-b="<%= @node_b %>">
+</div>

data/config/routes.rb

@@ -12,6 +12,8 @@ Profiler::Engine.routes.draw do
 
   root to: "profiles#index"
 
+  get "compare", to: "compare#show"
+
   resources :profiles, only: [:index, :show] do
     member do
       get :timeline
@@ -32,6 +34,9 @@ Profiler::Engine.routes.draw do
   get "health", to: "health#show"
 
   namespace :api do
+    get "compare", to: "compare#show"
+    get "compare/nodes", to: "compare#nodes"
+
     resources :profiles, only: [:index, :show, :destroy] do
       collection { delete :clear }
     end
@@ -45,6 +50,7 @@ Profiler::Engine.routes.draw do
       collection { delete :clear }
     end
     resources :outbound_http, only: [:index]
+    get "config", to: "config#show"
     get "toolbar/:token", to: "toolbar#show"
     post "ajax/link", to: "ajax#link"
     post "explain", to: "explain#create"

data/lib/profiler/configuration.rb

@@ -37,6 +37,9 @@ module Profiler
     # config.http_skip_hosts += Profiler::Configuration::LOCAL_HTTP_HOSTS.
     LOCAL_HTTP_HOSTS = [/\A127\.0\.0\.1\z/, /\Alocalhost\z/i, /\A::1\z/].freeze
 
+    # URL schemes the source links can use. Anything else is never turned into a link.
+    EDITOR_URL_SCHEMES = %w[vscode idea cursor].freeze
+
     attr_accessor :storage_options, :collectors,
                   :slow_query_threshold, :max_queries_warning, :sql_backtrace,
                   :track_memory, :allocated_objects_warning_threshold,
@@ -59,9 +62,12 @@ module Profiler
                   :cluster_heartbeat_interval, :cluster_offline_threshold,
                   :cluster_master, :cluster_secret, :cluster_require_secret,
                   :cluster_allow_insecure_http, :logger,
-                  :collector_circuit_breaker_enabled
+                  :collector_circuit_breaker_enabled,
+                  :peers, :peer_token, :peer_allow_insecure_http,
+                  :regression_duration_threshold, :regression_memory_threshold,
+                  :regression_query_threshold, :regression_cache_threshold
 
-    attr_reader :authorize_block, :enabled, :track_tests, :max_profiles
+    attr_reader :authorize_block, :enabled, :track_tests, :max_profiles, :editor_url_scheme, :editor_path_map
 
     def initialize
       @assigned = []
@@ -167,6 +173,17 @@ module Profiler
       # Profiler::Collectors::CircuitBreaker); false never stops one.
       @collector_circuit_breaker_enabled = true
       @collector_circuit_breaker_threshold = 3
+      @editor_url_scheme = "vscode"
+      @editor_path_map = {}
+      # Other instances whose profiles can be compared with this one's: [{ name:, url: }]. The only
+      # URLs the profiler ever calls to read a profile (Profiler::Peers). Empty: no outgoing call.
+      @peers = []
+      @peer_token = nil
+      @peer_allow_insecure_http = false
+      @regression_duration_threshold = 10  # % change threshold, changes below this are neutral
+      @regression_memory_threshold = 10    # % change threshold
+      @regression_query_threshold = 0      # % change threshold, 0 means any query count increase is a regression
+      @regression_cache_threshold = 5      # % change threshold for cache hit rate
     end
 
     attr_reader :collector_circuit_breaker_threshold
@@ -182,6 +199,28 @@ module Profiler
       end
     end
 
+    # The editor the file:line links open: "vscode", "idea" or "cursor" (String or Symbol). A
+    # value outside that list is kept as given, but #editor_link_scheme answers nil for it, so
+    # that no link is built.
+    def editor_url_scheme=(value)
+      @editor_url_scheme = value.nil? ? nil : value.to_s
+    end
+
+    # Container path prefix => host path prefix, for a server running in a container while the
+    # editor runs on the host: { "/app" => "/home/me/project" }. The longest matching prefix wins.
+    def editor_path_map=(value)
+      unless value.nil? || value.respond_to?(:to_h)
+        raise ArgumentError, "editor_path_map must be a Hash of container path => host path"
+      end
+
+      @editor_path_map = (value || {}).to_h.to_h { |from, to| [from.to_s, to.to_s] }
+    end
+
+    # The scheme the dashboard may use, or nil when the setting is not on the allow list.
+    def editor_link_scheme
+      EDITOR_URL_SCHEMES.include?(@editor_url_scheme) ? @editor_url_scheme : nil
+    end
+
     # Always a Pathname, whether set from a String or left to its default.
     def tmp_path
       @tmp_path || default_tmp_path

data/lib/profiler/mcp/server.rb

@@ -123,6 +123,7 @@ module Profiler
         require_relative "tools/list_slaves"
 
         slave_param = { type: "string", description: "Name of a connected slave profiler to target. Omit to use this profiler's own data." }
+        require_relative "tools/compare_profiles"
 
         [
           define_tool(
@@ -419,6 +420,20 @@ module Profiler
             description: "List all slave profilers connected to this master profiler, with their connection status.",
             input_schema: { properties: {} },
             handler: Tools::ListSlaves
+          ),
+          define_tool(
+            name: "compare_profiles",
+            description: "Compare two profiles, possibly from different instances listed in config.peers, and show metric deltas (duration, allocations, cache hit rate, views, HTTP) and SQL grouped by normalized fingerprint (new, gone, slower). Detects regressions based on configured thresholds.",
+            input_schema: {
+              properties: {
+                token_a: { type: "string", description: "Token of the baseline profile (required)" },
+                token_b: { type: "string", description: "Token of the profile to compare against baseline (required)" },
+                node_a: { type: "string", description: "Name of the config.peers entry holding profile A. Omit or \"local\" for this instance." },
+                node_b: { type: "string", description: "Name of the config.peers entry holding profile B. Omit or \"local\" for this instance." }
+              },
+              required: ["token_a", "token_b"]
+            },
+            handler: Tools::CompareProfiles
           )
         ].compact
       end

data/lib/profiler/mcp/tools/compare_profiles.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+module Profiler
+  module MCP
+    module Tools
+      class CompareProfiles
+        def self.call(params)
+          token_a = params["token_a"]
+          token_b = params["token_b"]
+
+          errors = []
+          errors << "Missing parameter: token_a" if token_a.nil? || token_a.empty?
+          errors << "Missing parameter: token_b" if token_b.nil? || token_b.empty?
+
+          if errors.any?
+            return [{ type: "text", text: "Error: #{errors.join(', ')}" }]
+          end
+
+          node_a = params["node_a"].to_s
+          node_b = params["node_b"].to_s
+
+          if token_a == token_b && node_a == node_b
+            return [{ type: "text", text: "Error: Cannot compare a profile with itself" }]
+          end
+
+          begin
+            diff = ProfileComparison.call(token_a, token_b, node_a: node_a, node_b: node_b)
+          rescue Profiler::Error => e
+            return [{ type: "text", text: e.message.start_with?("Profile not found") ? e.message : "Error: #{e.message}" }]
+          end
+
+          [{ type: "text", text: format_diff(diff) }]
+        end
+
+        def self.format_diff(diff)
+          pa = diff[:profile_a]
+          pb = diff[:profile_b]
+          m = diff[:metrics]
+
+          lines = []
+          lines << "# Profile Comparison\n"
+          lines << "**A:** `#{pa[:token]}` on #{pa[:node]}: #{pa[:method]} #{pa[:path]} (#{pa[:started_at]})"
+          lines << "**B:** `#{pb[:token]}` on #{pb[:node]}: #{pb[:method]} #{pb[:path]} (#{pb[:started_at]})\n"
+
+          unless diff[:same_endpoint]
+            lines << "⚠️ **Warning:** These profiles are from different endpoints - comparison may not be meaningful.\n"
+          end
+
+          lines << "## Scorecard\n"
+          lines << "| Metric | A | B | Delta | Status |"
+          lines << "|--------|---|---|-------|--------|"
+
+          append_metric(lines, "Duration (ms)", m[:duration])
+          append_metric(lines, "Allocated objects", m[:allocated_objects])
+          append_metric(lines, "DB Queries", m[:db_queries])
+          append_metric(lines, "DB Duration (ms)", m[:db_duration])
+          append_metric(lines, "Cache Hit Rate (%)", m[:cache_hit_rate])
+          append_metric(lines, "View Duration (ms)", m[:view_duration])
+          append_metric(lines, "HTTP Requests", m[:http_requests])
+          append_metric(lines, "HTTP Duration (ms)", m[:http_duration])
+
+          lines << ""
+          lines += format_sql(diff[:sql])
+          lines += format_database(diff[:collectors][:database])
+          lines += format_cache(diff[:collectors][:cache])
+          lines += format_views(diff[:collectors][:views])
+          lines += format_http(diff[:collectors][:http])
+
+          lines.join("\n")
+        end
+
+        def self.append_metric(lines, label, metric, formatter = nil)
+          return unless metric
+
+          fmt = formatter || ->(v) { v&.round(2)&.to_s || "-" }
+          val_a = fmt.call(metric[:value_a])
+          val_b = fmt.call(metric[:value_b])
+          delta = metric[:delta]
+          delta_pct = metric[:delta_pct]
+          sign = delta >= 0 ? "+" : ""
+          delta_str = "#{sign}#{delta.round(2)}"
+          delta_str += " (#{sign}#{delta_pct}%)" if delta_pct
+
+          icon = case metric[:status]
+                 when :improved then "✅"
+                 when :regression then "❌"
+                 else "➖"
+                 end
+
+          lines << "| #{label} | #{val_a} | #{val_b} | #{delta_str} | #{icon} |"
+        end
+
+        def self.markdown_table(title, guard_key, data, rows)
+          return [] unless data[guard_key]
+
+          lines = ["## #{title}\n", "| Metric | A | B |", "|--------|---|---|"]
+          rows.each { |label, a, b| lines << "| #{label} | #{a || '-'} | #{b || '-'} |" }
+          lines << ""
+          lines
+        end
+
+        def self.format_database(db)
+          markdown_table("Database", :total_queries_a, db, [
+            ["Total Queries",       db[:total_queries_a],                db[:total_queries_b]],
+            ["Total Duration (ms)", db[:total_duration_a]&.round(2),     db[:total_duration_b]&.round(2)],
+            ["Slow Queries",        db[:slow_queries_a],                 db[:slow_queries_b]],
+            ["Cached Queries",      db[:cached_queries_a],               db[:cached_queries_b]]
+          ])
+        end
+
+        def self.format_sql(sql)
+          lines = []
+          { new: "New queries (only in B)", gone: "Gone queries (only in A)", slower: "Slower queries" }.each do |key, title|
+            lines << "## #{title}\n"
+            if sql[key].empty?
+              lines << "None.\n"
+              next
+            end
+
+            lines << "| Query | Count A | Count B | Time A (ms) | Time B (ms) |"
+            lines << "|-------|---------|---------|-------------|-------------|"
+            sql[key].each do |q|
+              lines << "| `#{q[:fingerprint].to_s.gsub("|", "\\|").slice(0, 120)}` | #{q[:count_a]} | #{q[:count_b]} | " \
+                       "#{q[:total_duration_a]} | #{q[:total_duration_b]} |"
+            end
+            lines << ""
+          end
+          lines
+        end
+
+        def self.format_cache(cache)
+          markdown_table("Cache", :hit_rate_a, cache, [
+            ["Total Reads",  cache[:total_reads_a],  cache[:total_reads_b]],
+            ["Total Writes", cache[:total_writes_a], cache[:total_writes_b]],
+            ["Hit Rate (%)", cache[:hit_rate_a],     cache[:hit_rate_b]]
+          ])
+        end
+
+        def self.format_views(views)
+          markdown_table("Views", :total_duration_a, views, [
+            ["Templates",           views[:total_views_a],                views[:total_views_b]],
+            ["Partials",            views[:total_partials_a],             views[:total_partials_b]],
+            ["Total Duration (ms)", views[:total_duration_a]&.round(2),  views[:total_duration_b]&.round(2)]
+          ])
+        end
+
+        def self.format_http(http)
+          markdown_table("Outbound HTTP", :total_requests_a, http, [
+            ["Total Requests",      http[:total_requests_a],              http[:total_requests_b]],
+            ["Total Duration (ms)", http[:total_duration_a]&.round(2),   http[:total_duration_b]&.round(2)],
+            ["Slow Requests",       http[:slow_requests_a],               http[:slow_requests_b]],
+            ["Error Requests",      http[:error_requests_a],              http[:error_requests_b]]
+          ])
+        end
+      end
+    end
+  end
+end

data/lib/profiler/peers/peer_proxy.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require_relative "../peers"
+require_relative "../storage/token"
+
+module Profiler
+  module Peers
+    # Reads one profile from a peer listed in config.peers, through its /_profiler/api. The only
+    # target is the URL of the configuration entry found by name: no URL is ever taken as an argument.
+    class PeerProxy
+      # Same budget as Cluster::SlaveProxy: a slow peer must not hold the request thread for long.
+      OPEN_TIMEOUT = 5  # seconds
+      READ_TIMEOUT = 10 # seconds
+
+      attr_reader :name
+
+      def initialize(node, open_timeout: nil, read_timeout: nil)
+        peer = Peers.find!(node)
+        if (problem = Peers.token_problem)
+          raise Profiler::Error, "#{problem}: requests to peer #{peer.name.inspect} are refused"
+        end
+
+        @name = peer.name
+        @base_url = peer.url.to_s.chomp("/")
+        @open_timeout = open_timeout || OPEN_TIMEOUT
+        @read_timeout = read_timeout || READ_TIMEOUT
+      end
+
+      # nil when the peer has no such profile. A token the gem could not have issued is not
+      # asked for.
+      def load(token)
+        return nil unless Storage::Token.valid?(token)
+
+        data = get_json("/_profiler/api/profiles/#{Cluster::Security.escape_segment(token)}")
+        return nil if data.nil?
+        raise Profiler::Error, "Peer #{@name.inspect} sent an unexpected answer" unless data.is_a?(Hash) && data["token"]
+
+        require_relative "../models/profile"
+        Profiler::Models::Profile.from_hash(data.transform_keys(&:to_sym))
+      end
+
+      private
+
+      def get_json(path)
+        if (reason = Cluster::Security.api_path_denial(path))
+          raise Profiler::Error, "Refusing to send a request to peer #{@name.inspect}: #{reason}"
+        end
+
+        uri = URI("#{@base_url}#{path}")
+        req = Net::HTTP::Get.new(uri)
+        req[Profiler::FORGERY_PROTECTION_HEADER] = "1"
+        Peers.outgoing_headers.each { |header, value| req[header] = value }
+        # The profiler's own call, never recorded in the profile of the request that makes it.
+        resp = Profiler.untracked_http do
+          Net::HTTP.start(uri.hostname, uri.port, open_timeout: @open_timeout, read_timeout: @read_timeout,
+                                                  use_ssl: uri.scheme == "https") { |http| http.request(req) }
+        end
+        interpret(resp)
+      rescue SocketError, SystemCallError, Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError, IOError => e
+        raise Profiler::Error, "Peer #{@name.inspect} is unreachable (#{e.class}: #{e.message})"
+      end
+
+      # Net::HTTP never follows a redirect: a 3xx is reported rather than read as an answer.
+      def interpret(resp)
+        code = resp.code.to_s
+        return nil if code == "404"
+        raise Profiler::Error, "Peer #{@name.inspect} answered #{code} (redirect not followed)" if code.start_with?("3")
+        if %w[401 403].include?(code)
+          raise Profiler::Error, "Peer #{@name.inspect} refused the request (#{code}): check that both instances " \
+                                 "share the same config.peer_token"
+        end
+        raise Profiler::Error, "Peer #{@name.inspect} answered #{code}" unless code == "200"
+
+        JSON.parse(resp.body.to_s)
+      rescue JSON::ParserError
+        raise Profiler::Error, "Peer #{@name.inspect} answered something that is not JSON"
+      end
+    end
+  end
+end

data/lib/profiler/peers.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "ipaddr"
+require "uri"
+require "active_support/security_utils"
+require_relative "cluster/security"
+
+module Profiler
+  # Static, explicit list of other instances (config.peers) whose profiles can be read to be
+  # compared with the local ones. Deliberately separate from the master/slave cluster: nothing
+  # here is registered at runtime, and the URLs come from the operator's configuration only,
+  # never from a request, an API parameter or an MCP tool argument.
+  module Peers
+    TOKEN_HEADER = "X-Profiler-Peer-Token"
+    TOKEN_ENV_KEY = "HTTP_X_PROFILER_PEER_TOKEN"
+    MIN_TOKEN_LENGTH = 32
+    # The names that mean "this instance" in a node selector.
+    LOCAL_NODE = "local"
+
+    Peer = Struct.new(:name, :url)
+
+    class << self
+      # The validated peers, checked once per configured list (the list is static and trusted).
+      # Raises Profiler::Error naming the first invalid entry.
+      def all
+        list = Profiler.configuration.peers
+        return [] if list.nil? || list.empty?
+
+        cache = @validated
+        return cache[1] if cache && cache[0].equal?(list) && cache[2] == list.hash
+
+        peers = validate!(list)
+        @validated = [list, peers, list.hash]
+        peers
+      end
+
+      def names
+        all.map(&:name)
+      end
+
+      def local?(node)
+        node.nil? || node.to_s.strip.empty? || node.to_s == LOCAL_NODE
+      end
+
+      # The peer called node, or a Profiler::Error. Never builds a peer from anything but config.peers.
+      def find!(node)
+        peers = all
+        peer = peers.find { |p| p.name == node.to_s }
+        return peer if peer
+
+        known = peers.empty? ? "none configured (config.peers is empty)" : peers.map(&:name).join(", ")
+        raise Profiler::Error, "Unknown node #{node.to_s.inspect}: it is not in config.peers (known nodes: #{known})"
+      end
+
+      # Why the configured token cannot be used, or nil when it can.
+      def token_problem
+        token = Profiler.configuration.peer_token.to_s
+        return "No config.peer_token is configured" if token.strip.empty?
+        return nil if token.strip.length >= MIN_TOKEN_LENGTH
+
+        "config.peer_token is shorter than #{MIN_TOKEN_LENGTH} characters, so it is ignored as if none were configured"
+      end
+
+      def configured_token?
+        token_problem.nil?
+      end
+
+      def outgoing_headers
+        { TOKEN_HEADER => Profiler.configuration.peer_token.to_s }
+      end
+
+      # Constant-time comparison of the token a request carries; false when none is configured.
+      def valid_token?(presented)
+        return false unless configured_token?
+        return false if presented.to_s.empty?
+
+        ActiveSupport::SecurityUtils.secure_compare(presented.to_s, Profiler.configuration.peer_token.to_s)
+      end
+
+      def request_token_valid?(request)
+        valid_token?(request.get_header(TOKEN_ENV_KEY))
+      end
+
+      # Logged once at boot when peers are configured without a usable token: every call to a
+      # peer is then refused.
+      def warn_about_configuration(logger)
+        return if Profiler.configuration.peers.to_a.empty?
+        return unless (problem = token_problem)
+
+        Profiler.log_warn("Peers: #{problem}: comparing profiles across nodes is refused. Generate one with " \
+                          "`ruby -rsecurerandom -e 'puts SecureRandom.hex(32)'` and give the same value to " \
+                          "every instance.", logger: logger)
+      end
+
+      def reset!
+        @validated = nil
+      end
+
+      private
+
+      def validate!(list)
+        raise Profiler::Error, "config.peers must be an Array of { name:, url: }" unless list.is_a?(Array)
+
+        peers = list.each_with_index.map { |entry, index| build_peer(entry, index) }
+        duplicate = peers.map(&:name).tally.find { |_, count| count > 1 }
+        raise Profiler::Error, "config.peers: the name #{duplicate[0].inspect} is used twice" if duplicate
+
+        peers
+      end
+
+      def build_peer(entry, index)
+        unless entry.respond_to?(:to_h) && !entry.is_a?(Array)
+          raise Profiler::Error, "config.peers[#{index}] must be a Hash with :name and :url"
+        end
+
+        hash = entry.to_h.transform_keys(&:to_s)
+        name = hash["name"].to_s.strip
+        unless name.match?(/\A[A-Za-z0-9][A-Za-z0-9._-]{0,63}\z/) && name != LOCAL_NODE
+          raise Profiler::Error, "config.peers[#{index}]: name #{hash["name"].inspect} must be 1 to 64 letters, " \
+                                 "digits, dots, dashes or underscores, and cannot be #{LOCAL_NODE.inspect}"
+        end
+        if (reason = url_denial(hash["url"]))
+          raise Profiler::Error, "config.peers[#{index}] (#{name}): #{reason}"
+        end
+
+        Peer.new(name, Cluster::Security.normalized_url(hash["url"]).freeze)
+      end
+
+      # nil when the peer URL is acceptable: a plain http(s) URL, with HTTPS required unless the
+      # host is a loopback address or config.peer_allow_insecure_http is set.
+      def url_denial(url)
+        target = Cluster::Security.normalize(url)
+        return "#{url.inspect} is not a valid http(s) URL" unless target
+        return nil if target[:scheme] == "https" || Cluster::Security.loopback_host?(target[:host])
+        return nil if Profiler.configuration.peer_allow_insecure_http
+
+        "#{url} uses plain HTTP to a host that is not a loopback address: HTTPS is required " \
+          "(or set config.peer_allow_insecure_http = true)"
+      end
+    end
+  end
+end

data/lib/profiler/profile_comparison.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "peers"
+require_relative "peers/peer_proxy"
+require_relative "profile_diff"
+
+module Profiler
+  # Loads two profiles, each from this instance or from a peer of config.peers, and diffs them.
+  # The node is a name in config.peers (or blank / "local"); it is never a URL.
+  module ProfileComparison
+    NotFound = Class.new(Profiler::Error)
+
+    class << self
+      # Both nodes are resolved before any profile is read, so an unknown node fails
+      # without a single outgoing call.
+      def call(token_a, token_b, node_a: nil, node_b: nil)
+        sources = [node_a, node_b].map { |node| source_for(node) }
+        profile_a = sources[0].load(token_a)
+        profile_b = sources[1].load(token_b)
+
+        missing = []
+        missing << "Profile not found: #{token_a}#{on_node(node_a)}" unless profile_a
+        missing << "Profile not found: #{token_b}#{on_node(node_b)}" unless profile_b
+        raise NotFound, missing.join("\n") if missing.any?
+
+        ProfileDiff.new(profile_a, profile_b, node_a: label(node_a), node_b: label(node_b)).compute
+      end
+
+      private
+
+      def source_for(node)
+        Peers.local?(node) ? Profiler.storage : Peers::PeerProxy.new(node)
+      end
+
+      def label(node)
+        Peers.local?(node) ? Peers::LOCAL_NODE : node.to_s
+      end
+
+      def on_node(node)
+        Peers.local?(node) ? "" : " (node #{node})"
+      end
+    end
+  end
+end