rails-profiler 0.34.0 → 0.34.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b6a0140a91e984bd6d06d7277a149c2a7eeace21ec53c3d3ddc1acb7eb137879
-  data.tar.gz: 730abdd8332a638e3d78db3d74378ab10fc1280f9d5f83f11b327409b076c1e3
+  metadata.gz: 48da35ed6e2dfe679099e6312f3e763d4be32102f3a814c442c6b971d793617b
+  data.tar.gz: 3b417051b4cf1e9c833fd8fd057e813f8a5804ecf1a12ee901b679b9788a36ff
 SHA512:
-  metadata.gz: '09a3cac5a02d3407f8a03dad19154d8f36c5dd57e8c1f5d9b0021aad015e7e459a4305592e68defb796672a9cbd29b40c48b2933cff56b2fe340c3ae370de767'
-  data.tar.gz: dda83a3c7086e4679766abe06d0dc5e88befc5e9ebebb19a87ec605a3b268a2ab81fccef0274e8170043bb4c6ab452f68307e5a1546921b55b418289427fc805
+  metadata.gz: 067a9332736da6de166e68414f19fe17d36d1e312caa430ace65ed58c6910afc697b17b658613df72c95b8c718a03488e853a2472a194a1e43a85935f2bf4e32
+  data.tar.gz: 3ae810aa41f27dfabcfa68e0a94ac2bb7e34e0b860d8097d2d5fea1c0216b3f26d3a23d243faab56a03cebb9a1b7840e234d9ec7c53cb4c83bf2c2cc49dd6029

data/CHANGELOG.md

@@ -19,6 +19,28 @@ every commit of every tag interval is accounted for one way or the other.
 
 ## [Unreleased]
 
+## [0.34.1] - 2026-10-15
+
+<!-- stamped -->
+
+### Security
+
+- **Explain:** The Explain button, `POST /_profiler/api/explain` and the MCP `explain_query` tool
+  now only run in the `development` and `test` environments, even where an application sets
+  `enabled = true`. Elsewhere, `production` and `staging` included, they are refused before
+  anything reaches the database: a `403` from the endpoint, an error from the tool. PostgreSQL's
+  `EXPLAIN ANALYZE` runs the query it explains, so a costly `SELECT` used to run for real on the
+  production database. Set `config.allow_explain_outside_development = true` to allow it there
+  anyway (false by default). The description of `explain_query` given to MCP clients now says so;
+  it claimed the tool was limited to development and test, which nothing enforced.
+- **API:** An unexpected error no longer sends its message to the client. `POST
+  /_profiler/api/explain` answers `500` with `Explain failed`, `POST /_profiler/api/ajax/link`
+  with `Could not link the Ajax request`, the slave proxy (`/_profiler/api/slaves/:name/...`)
+  `502` with `Proxy error`, and `explain_query` with `EXPLAIN failed`. The message, which could
+  hold the SQL of the query, an internal file path or the address of a slave, goes to the
+  application log instead. The profiler's own refusals (a query that is not read-only, an index
+  out of range, an unknown or offline slave) still give their reason.
+
 ## [0.34.0] - 2026-10-15
 
 <!-- stamped -->

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

@@ -32,8 +32,10 @@ module Profiler
         Profiler.storage.save(child_token, child_profile)
 
         render json: { success: true }
-      rescue => e
-        render json: { error: e.message }, status: :internal_server_error
+      rescue StandardError => e
+        # The storage's message can name an internal path: the log only.
+        Profiler.log_error("Ajax: could not link the request #{child_token.to_s.inspect} to #{parent_token.inspect}", e)
+        render json: { error: "Could not link the Ajax request" }, status: :internal_server_error
       end
     end
   end

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

@@ -6,8 +6,8 @@ module Profiler
   module Api
     class ExplainController < ApplicationController
       def create
-        unless Profiler.configuration.enabled
-          return render json: { error: "EXPLAIN is only available when the profiler is enabled" }, status: :forbidden
+        if (reason = Profiler::ExplainRunner.refusal)
+          return render json: { error: reason }, status: :forbidden
         end
 
         token       = params[:token].to_s
@@ -19,10 +19,12 @@ module Profiler
 
         result = Profiler::ExplainRunner.run(token, query_index)
         render json: result
-      rescue ArgumentError => e
+      rescue Profiler::ExplainRunner::RefusedError => e
         render json: { error: e.message }, status: :unprocessable_entity
-      rescue => e
-        render json: { error: e.message }, status: :internal_server_error
+      rescue StandardError => e
+        # The database's message carries the SQL, and sometimes a path: the log only.
+        Profiler.log_error("Explain: failed for query #{query_index} of profile #{token.inspect}", e)
+        render json: { error: "Explain failed" }, status: :internal_server_error
       end
     end
   end

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

@@ -26,10 +26,13 @@ module Profiler
                  end
 
         render json: result
+      # The profiler's own refusals (unknown or offline slave, refused URL, missing secret).
       rescue Profiler::Error => e
         render json: { error: e.message }, status: :bad_gateway
-      rescue => e
-        render json: { error: "Proxy error: #{e.message}" }, status: :bad_gateway
+      rescue StandardError => e
+        # A network error names the slave's address, and sometimes a path: the log only.
+        Profiler.log_error("SlaveProxy: could not forward #{request.method} to slave profiler #{params[:slave_name].to_s.inspect}", e)
+        render json: { error: "Proxy error" }, status: :bad_gateway
       end
 
       private

data/lib/profiler/configuration.rb

@@ -48,7 +48,7 @@ module Profiler
                   :track_jobs,
                   :track_console,
                   :apply_env_overrides_when_disabled, :restrict_storage_permissions,
-                  :test_runner_allow_undiscovered_files,
+                  :test_runner_allow_undiscovered_files, :allow_explain_outside_development,
                   :track_mailers, :capture_mail_body, :sanitize_mailer_recipients, :mailer_skip_actions,
                   :compress_bodies, :compress_body_threshold, :max_captured_body_bytes, :max_captured_log_bytes,
                   :redact_sensitive_data, :filter_parameters, :env_allowlist,
@@ -108,6 +108,10 @@ module Profiler
       # The test runner only runs the files listed by its discovery. true restores the
       # previous behavior: any file under the Rails root.
       @test_runner_allow_undiscovered_files = false
+      # Explain (the Database tab button, POST /_profiler/api/explain, the explain_query MCP tool)
+      # only runs in the development and test environments, even with enabled = true elsewhere:
+      # PostgreSQL's EXPLAIN ANALYZE runs the query. true allows it in every environment.
+      @allow_explain_outside_development = false
       @track_mailers = true
       @capture_mail_body = false
       @sanitize_mailer_recipients = false

data/lib/profiler/explain_runner.rb

@@ -11,9 +11,39 @@ module Profiler
   # what no reading of the statement can rule out (a function with a side effect),
   # on a connection of its own that is closed afterwards, in a transaction that is
   # always rolled back, read-only and time-limited on PostgreSQL.
+  #
+  # It only runs in the development and test environments, whatever config.enabled says,
+  # unless config.allow_explain_outside_development is set: PostgreSQL's EXPLAIN ANALYZE runs
+  # the query, and a costly SELECT would run for real on the production database.
   module ExplainRunner
-    # An ArgumentError, so callers answer it as a bad request (422, MCP error).
-    class UnsafeStatementError < ArgumentError; end
+    # A request the runner refuses, with a message written for the caller: an ArgumentError,
+    # so callers answer it as a bad request (422, MCP error). Any other error is internal, and
+    # its message (SQL, paths) stays in the server log.
+    class RefusedError < ArgumentError; end
+
+    class UnsafeStatementError < RefusedError; end
+
+    # The environments EXPLAIN runs in without config.allow_explain_outside_development.
+    ENVIRONMENTS = %w[development test].freeze
+
+    NOT_ENABLED = "EXPLAIN is only available when the profiler is enabled"
+    OUTSIDE_DEVELOPMENT = "EXPLAIN is only available in the development and test environments " \
+                          "(config.allow_explain_outside_development allows it in the others)"
+
+    # Why EXPLAIN may not run in this process, or nil when it may. Without Rails, the
+    # environment is unknown and EXPLAIN is refused.
+    def self.refusal
+      config = Profiler.configuration
+      return NOT_ENABLED unless config.enabled
+      return nil if config.allow_explain_outside_development == true
+      return nil if ENVIRONMENTS.include?(current_environment)
+
+      OUTSIDE_DEVELOPMENT
+    end
+
+    def self.current_environment
+      Rails.env.to_s if defined?(Rails) && Rails.respond_to?(:env) && Rails.env
+    end
 
     # PostgreSQL's EXPLAIN ANALYZE runs the query: a slow one is stopped after this.
     PROBE_STATEMENT_TIMEOUT = "30s"
@@ -21,29 +51,29 @@ module Profiler
     # @param profile_token [String]
     # @param query_index   [Integer]
     # @return [Hash] { result:, format: "json"|"text", adapter: String }
-    #         or raises ArgumentError / RuntimeError
+    #         or raises SecurityError (see .refusal), RefusedError, or any error of the database
     def self.run(profile_token, query_index)
-      unless Profiler.configuration.enabled
-        raise SecurityError, "EXPLAIN is only available when the profiler is enabled"
+      if (reason = refusal)
+        raise SecurityError, reason
       end
 
       profile = Profiler.storage.load(profile_token)
-      raise ArgumentError, "Profile not found: #{profile_token}" unless profile
+      raise RefusedError, "Profile not found: #{profile_token}" unless profile
 
       db_data = profile.collector_data("database")
-      raise ArgumentError, "No database data in this profile" unless db_data && db_data["queries"]
+      raise RefusedError, "No database data in this profile" unless db_data && db_data["queries"]
 
       queries = db_data["queries"]
       query_index = query_index.to_i
       unless query_index >= 0 && query_index < queries.size
-        raise ArgumentError, "Query index #{query_index} out of range (0..#{queries.size - 1})"
+        raise RefusedError, "Query index #{query_index} out of range (0..#{queries.size - 1})"
       end
 
       query = queries[query_index]
       sql   = query["sql"].to_s
       binds = Array(query["binds"])
       if binds.include?(Redaction::MASK)
-        raise ArgumentError, "EXPLAIN refused for query #{query_index}: one of its bind values was " \
+        raise RefusedError, "EXPLAIN refused for query #{query_index}: one of its bind values was " \
                              "filtered when captured (config.filter_parameters), so the query cannot be rebuilt"
       end
 

data/lib/profiler/mcp/server.rb

@@ -176,7 +176,7 @@ module Profiler
           ),
           define_tool(
             name: "explain_query",
-            description: "Run EXPLAIN ANALYZE on a specific query from a profile. Returns the query execution plan with cost and row estimates. Only read-only statements (SELECT, WITH ... SELECT, TABLE, VALUES) are explained, in a transaction always rolled back; other queries return an error. Only available in development/test environments.",
+            description: "Run EXPLAIN ANALYZE on a specific query from a profile. Returns the query execution plan with cost and row estimates. Only read-only statements (SELECT, WITH ... SELECT, TABLE, VALUES) are explained, in a transaction always rolled back; other queries return an error. Refused with an error unless the application that runs it (this one, or the slave given) has the profiler enabled and runs in the development or test environment; config.allow_explain_outside_development = true lifts the environment check.",
             input_schema: {
               properties: {
                 token: { type: "string", description: "Profile token, or 'latest' for the most recent profile (required)" },

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

@@ -26,8 +26,8 @@ module Profiler
             return [{ type: "text", text: text }]
           end
 
-          unless Profiler.configuration.enabled
-            return [{ type: "text", text: "Error: EXPLAIN is only available when the profiler is enabled" }]
+          if (reason = Profiler::ExplainRunner.refusal)
+            return [{ type: "text", text: "Error: #{reason}" }]
           end
 
           data = Profiler::ExplainRunner.run(token, query_index.to_i)
@@ -47,10 +47,12 @@ module Profiler
           end
 
           [{ type: "text", text: lines.join("\n") }]
-        rescue ArgumentError => e
+        rescue Profiler::ExplainRunner::RefusedError => e
           [{ type: "text", text: "Error: #{e.message}" }]
-        rescue => e
-          [{ type: "text", text: "EXPLAIN failed: #{e.message}" }]
+        rescue StandardError => e
+          # The database's message carries the SQL, and sometimes a path: the log only.
+          Profiler.log_error("MCP explain_query: failed for query #{query_index.to_i} of profile #{token.to_s.inspect}", e)
+          [{ type: "text", text: "EXPLAIN failed (the application log has the details)" }]
         end
       end
     end

data/lib/profiler/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Profiler
-  VERSION = "0.34.0"
+  VERSION = "0.34.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-profiler
 version: !ruby/object:Gem::Version
-  version: 0.34.0
+  version: 0.34.1
 platform: ruby
 authors:
 - Sébastien Duplessy