rails-profiler 0.33.3 → 0.34.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 533fac499cbab38112f1be4ab7d066761f0f0cea1b22d76e4d355059ef03d9dd
-  data.tar.gz: b8d37a14501188a671be2ee4876b8ce9678641cca8acbd836e456ea62249ef48
+  metadata.gz: 48da35ed6e2dfe679099e6312f3e763d4be32102f3a814c442c6b971d793617b
+  data.tar.gz: 3b417051b4cf1e9c833fd8fd057e813f8a5804ecf1a12ee901b679b9788a36ff
 SHA512:
-  metadata.gz: 7daad08c5c0b6a119933341e7b1a1ba28d746c2801eef525a83dd54388c85a30bfa68a7240d2e99705992e622929df012b98676f0ec396a028fff759690910da
-  data.tar.gz: d205ba6d72f09ca00d1eb714db57f99052e64297caddb33999c8c6ae87ae380874cf015af986d0065d7b76c949388a813f3f397adae3fe23b7f5a1e6bdbcbc48
+  metadata.gz: 067a9332736da6de166e68414f19fe17d36d1e312caa430ace65ed58c6910afc697b17b658613df72c95b8c718a03488e853a2472a194a1e43a85935f2bf4e32
+  data.tar.gz: 3ae810aa41f27dfabcfa68e0a94ac2bb7e34e0b860d8097d2d5fea1c0216b3f26d3a23d243faab56a03cebb9a1b7840e234d9ec7c53cb4c83bf2c2cc49dd6029

data/CHANGELOG.md

@@ -19,6 +19,72 @@ 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 -->
+
+### Added
+
+- **MCP:** `config.mcp_read_only = true` leaves out the tools that change something:
+  `run_tests`, `clear_profiles`, `set_env_var`, `delete_env_var`, `reset_env_var` and
+  `reset_all_env_vars`. They are not listed by `tools/list`, and a client that calls one by name
+  gets a "tool not found" error; the tools that only read stay. False by default. The gem's
+  `profiler-mcp` executable does not boot the application, so it never reads the option: set
+  `PROFILER_MCP_READ_ONLY=1` in the environment the MCP client starts it with. The variable works
+  with `rake profiler:mcp` and the HTTP transport too, and never turns read-only off.
+
+### Changed
+
+- **Env overrides:** An override saved by an earlier version for a name the profiler now refuses,
+  such as `DATABASE_URL`, `PRIMARY_DATABASE_URL`, `LD_PRELOAD` or `HTTPS_PROXY`, is no longer
+  applied: not at boot, not before a Sidekiq job, not in the test runner. It stays in the file
+  until reset, and a warning gives how many were left out, never their names. Set such a variable
+  in the shell that starts the application instead.
+
+### Fixed
+
+- **Env overrides:** The Env tab, `set_env_var` and `delete_env_var` refuse a name that is not
+  made of letters, digits and underscores (`A=B`, `MY-VAR`), and the variables that select the
+  database, the secrets or the network of the application, or make a process load other code:
+  `DATABASE_URL` and every name ending in `_DATABASE_URL`, every name starting with `PG` or
+  `MYSQL_`, `RAILS_MASTER_KEY`, every proxy variable in any case (`http_proxy`, `HTTPS_PROXY`),
+  `SSL_CERT_FILE`, `SSL_CERT_DIR`, `OPENSSL_CONF`, `GCONV_PATH`, `IRBRC`, `PRYRC`, `ZDOTDIR`,
+  `LD_PRELOAD`, `RUBYOPT` and the others listed in the docs. Before, any of these could be set,
+  `DATABASE_URL` included. The refusal comes before anything is written: a 422 from the endpoint,
+  an error from the tool. The list cannot be complete: a gem may read a variable of its own.
+- **Env overrides:** A value holding a NUL byte is refused the same way. Before, it was written to
+  the file, then the tool failed with an internal error, and every process logged the same error
+  again before each Sidekiq job.
+- **Env overrides:** A reset now reaches every process that applied the override, each Sidekiq
+  process and Puma worker, not only the first one to read the file: each puts back the value it
+  had before. A process that never applied the override is left alone.
+- **Env overrides:** The overrides file is no longer read and parsed again before every Sidekiq
+  job while it does not change. A change written within two seconds of the previous one is never
+  missed, on ext4 too, where the file system reuses the inode and the modification time can stay
+  the same.
+
 ## [0.33.3] - 2026-10-14
 
 <!-- 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/env_vars_controller.rb

@@ -24,14 +24,20 @@ module Profiler
           return
         end
 
-        if Profiler::EnvOverrideStore.reserved_key?(key)
-          render json: { error: "#{Profiler::EnvOverrideStore::RESERVED_KEY_ERROR}; #{key} was left unchanged" },
-                 status: :unprocessable_entity
+        # Checked before the store is written: a refused key never reaches the file nor ENV.
+        if (reason = Profiler::EnvKeyPolicy.rejection(key))
+          render json: { error: "#{reason}; #{key} was left unchanged" }, status: :unprocessable_entity
           return
         end
 
         value = params[:value]
 
+        # A value ENV cannot hold is refused before the store is written, like a refused key.
+        if (reason = Profiler::EnvKeyPolicy.value_rejection(key, value))
+          render json: { error: "#{reason}; #{key} was left unchanged" }, status: :unprocessable_entity
+          return
+        end
+
         if Profiler::Redaction.mask?(value)
           render json: { error: "#{Profiler::Redaction::MASK} is the mask the profiler shows in place of a " \
                                 "hidden value, not a value; #{key} was left unchanged" },

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/exe/profiler-mcp

@@ -1,6 +1,11 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
+# The MCP server over stdio, without the application: its initializers do not run here, so
+# config.mcp_read_only set there has no effect. Set PROFILER_MCP_READ_ONLY=1 in the environment the
+# MCP client gives this process to leave out the write tools (Profiler::MCP::Server.read_only?).
+# `bundle exec rake profiler:mcp` boots the application and reads both.
+
 require "bundler/setup"
 require "profiler"
 require "profiler/mcp/server"

data/lib/profiler/configuration.rb

@@ -40,7 +40,7 @@ module Profiler
     attr_accessor :storage_options, :collectors,
                   :slow_query_threshold, :max_queries_warning, :sql_backtrace,
                   :track_memory, :allocated_objects_warning_threshold,
-                  :mcp_enabled, :mcp_transport, :mcp_port,
+                  :mcp_enabled, :mcp_transport, :mcp_port, :mcp_read_only,
                   :authorization_mode, :extension_cors_enabled,
                   :cors_allowed_origins, :api_forgery_protection, :frame_ancestors,
                   :track_ajax, :ajax_skip_paths,
@@ -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,
@@ -79,6 +79,10 @@ module Profiler
       @mcp_enabled = false
       @mcp_transport = :stdio
       @mcp_port = 3001
+      # true leaves out of the MCP server every tool that changes something: run_tests,
+      # clear_profiles and the env tools that set, delete or reset a variable
+      # (Profiler::MCP::Server::WRITE_TOOLS). Read when the server is built, at the first MCP call.
+      @mcp_read_only = false
       @authorization_mode = :allow_local
       @authorize_block = nil
       @max_profiles = 100
@@ -104,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/env_key_policy.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Profiler
+  # Which environment variables the profiler may change: the Env tab, the MCP env tools, the
+  # overrides replayed by EnvOverrideStore#apply! and the environment of the test runner all
+  # read this one list.
+  #
+  # It is a deny list, chosen over an allow list on purpose (DECISIONS.md): the Env tab exists for
+  # the application's own variables, feature flags and API URLs, whose names nobody can enumerate
+  # in the gem. A deny list is by nature incomplete: any gem, library or tool the application uses
+  # can read a variable of its own tomorrow, a new database adapter or HTTP client among them, and
+  # no list written here can foresee it. The names below are the ones known to redirect the
+  # application's connections, hand over its secrets, or make a process load other code; a
+  # variable left out here can still be set in the shell that starts the application.
+  module EnvKeyPolicy
+    # Set by the test runner in the environment of the test process.
+    TEST_RUNNER_CHILD_ENV = "PROFILER_TEST_RUNNER_CHILD"
+    RESERVED_KEY_ERROR = "#{TEST_RUNNER_CHILD_ENV} is reserved for the test runner"
+
+    # Select the environment, the database or the secrets of the application, where it connects
+    # and which certificates it trusts, or the profiler's own read-only switch.
+    PROTECTED_KEYS = %w[
+      RAILS_ENV RACK_ENV DATABASE_URL SECRET_KEY_BASE RAILS_MASTER_KEY PROFILER_TEST_RUNNER_CHILD
+      PROFILER_MCP_READ_ONLY SSL_CERT_FILE SSL_CERT_DIR
+    ].freeze
+    # PG: libpq (PGHOST, PGPASSWORD, PGSERVICEFILE...). MYSQL_: the MySQL client (MYSQL_PWD,
+    # MYSQL_HOST...). OPENSSL_: OPENSSL_CONF and OPENSSL_MODULES can load a shared library.
+    PROTECTED_PREFIXES = %w[PG MYSQL_ OPENSSL_].freeze
+    # _DATABASE_URL: ActiveRecord reads PRIMARY_DATABASE_URL (any <name>_DATABASE_URL of a
+    # multi-database configuration) before DATABASE_URL. _PROXY: http_proxy, HTTPS_PROXY, no_proxy
+    # and the others, read again by Net::HTTP at each connection, whatever their case.
+    PROTECTED_SUFFIXES = %w[_DATABASE_URL _PROXY].freeze
+
+    # Overrides of these variables make a process, or the shell shims (rbenv, asdf) that start
+    # it, load or run code other than its own.
+    CODE_LOADING_KEYS = %w[
+      SPEC_OPTS TESTOPTS TEST PATH HOME XDG_CONFIG_HOME GEMRC NODE_OPTIONS NODE_PATH
+      SHELLOPTS BASHOPTS PS4 ENV CDPATH IFS ZDOTDIR GCONV_PATH LOCPATH IRBRC PRYRC PRY_RC
+      LESSOPEN LESSCLOSE PAGER EDITOR VISUAL JAVA_TOOL_OPTIONS JDK_JAVA_OPTIONS _JAVA_OPTIONS
+    ].freeze
+    CODE_LOADING_PREFIXES = %w[
+      RUBY GEM_ BUNDLE_ BUNDLER_ LD_ DYLD_ BASH_ RBENV_ ASDF_ RVM_ CHRUBY GIT_ BOOTSNAP_
+      PYTHON PERL5
+    ].freeze
+
+    # Letters, digits and underscores, not starting with a digit. Anything else, "=" or a NUL
+    # byte above all, either cannot be written into ENV or is not a name a shell can set.
+    ENV_NAME = /\A[A-Z_][A-Z0-9_]*\z/i
+
+    module_function
+
+    def valid_name?(key)
+      ENV_NAME.match?(key.to_s)
+    end
+
+    def reserved?(key)
+      key.to_s.upcase == TEST_RUNNER_CHILD_ENV
+    end
+
+    def protected?(key)
+      name = key.to_s.upcase
+      PROTECTED_KEYS.include?(name) ||
+        PROTECTED_PREFIXES.any? { |prefix| name.start_with?(prefix) } ||
+        PROTECTED_SUFFIXES.any? { |suffix| name.end_with?(suffix) }
+    end
+
+    # True for a name that is not valid, too: the test runner leaves those out with the others.
+    def code_loading?(key)
+      name = key.to_s.upcase
+      return true unless valid_name?(name)
+
+      CODE_LOADING_KEYS.include?(name) || CODE_LOADING_PREFIXES.any? { |prefix| name.start_with?(prefix) }
+    end
+
+    # Why the profiler refuses to set or delete key, or nil when it may.
+    def rejection(key)
+      name = key.to_s
+      return "key cannot be blank" if name.strip.empty?
+      return RESERVED_KEY_ERROR if reserved?(name)
+      unless valid_name?(name)
+        return "#{name.inspect} is not a valid environment variable name " \
+               "(letters, digits and underscores, not starting with a digit)"
+      end
+      if protected?(name) || code_loading?(name)
+        return "#{name} is protected: the profiler does not change the variables that select the " \
+               "environment, the database, the secrets or the network of the application, nor " \
+               "those that make a process load other code"
+      end
+
+      nil
+    end
+
+    # Why the profiler refuses to set key to value, or nil when it may. A NUL byte cannot be held
+    # by an environment variable: ENV[]= raises on it.
+    def value_rejection(key, value)
+      return nil unless value.to_s.include?("\0")
+
+      "the value of #{key} contains a NUL byte, which an environment variable cannot hold"
+    end
+
+    def allowed?(key)
+      rejection(key).nil?
+    end
+  end
+end

data/lib/profiler/env_override_store.rb

@@ -3,6 +3,7 @@
 require "json"
 require "fileutils"
 require_relative "storage/private_files"
+require_relative "env_key_policy"
 
 module Profiler
   class EnvOverrideStore
@@ -26,17 +27,37 @@ module Profiler
     # File format: { "KEY" => { "value" => "...", "original" => "..." } }
     # Sentinels for "value":
     #   DELETED_SENTINEL  → ENV.delete(key)
-    #   RESTORE_SENTINEL  → restore ENV[key] to "original" (cleaned up after apply!)
+    #   RESTORE_SENTINEL  → every process that applied the key puts back the value it had before
+    #                       (apply!). The entry carries "reset_at" and stays RESTORE_TTL seconds,
+    #                       so that each Sidekiq process and Puma worker sees it, not only the first.
+
+    # How long a RESTORE entry stays in the file. A process that runs no job for longer keeps the
+    # override until it restarts.
+    RESTORE_TTL = 7 * 24 * 60 * 60
+
+    # How old the overrides file must be before apply! keeps its content between calls
+    # (cached_overrides).
+    CACHE_SETTLE_SECONDS = 2
 
     def initialize
       # What ENV held in this process before set, delete or apply! changed a key. Where the
       # overrides are blocked, a reset restores these and never the file's "original" values,
-      # which come from whatever machine wrote the file.
+      # which come from whatever machine wrote the file. apply! restores these too, so it knows
+      # which keys this process changed and has to put back.
       @process_originals = {}
       @process_originals_lock = Mutex.new
+      # [signature of the file, parsed overrides] as apply! last read them.
+      @cached_overrides = nil
+      @skipped_keys_logged = nil
     end
 
     def set(key, value)
+      # Before the file is written: an entry ENV cannot hold would fail in every process that
+      # applies it.
+      if (reason = EnvKeyPolicy.value_rejection(key, value))
+        raise Error, "could not set #{key}: #{reason}"
+      end
+
       surfacing("set #{key}") do
         remember_process_original(key)
         update_overrides do |overrides|
@@ -61,7 +82,7 @@ module Profiler
         update_overrides do |overrides|
           entry = overrides[key]
           # Keep a RESTORE entry so Sidekiq workers pick it up on next job
-          overrides[key] = { "value" => RESTORE_SENTINEL, "original" => entry["original"] } if entry
+          overrides[key] = restore_entry(entry["original"]) if entry
         end
       end
 
@@ -74,9 +95,12 @@ module Profiler
       surfacing("reset the overrides") do
         update_overrides do |overrides|
           overrides.each do |key, entry|
+            # Already reset: its reset_at stays, so that it still expires.
+            next if restore_entry?(entry)
+
             originals[key] = entry.is_a?(Hash) ? entry["original"] : nil
             # Leave a RESTORE sentinel for Sidekiq workers to pick up
-            overrides[key] = { "value" => RESTORE_SENTINEL, "original" => originals[key] }
+            overrides[key] = restore_entry(originals[key])
           end
         end
       end
@@ -116,47 +140,34 @@ module Profiler
 
     # Set by the test runner in the environment of the test process, to which it already gave
     # the admitted overrides only (TestRunner::Runner.build_env).
-    TEST_RUNNER_CHILD_ENV = "PROFILER_TEST_RUNNER_CHILD"
-    RESERVED_KEY_ERROR = "#{TEST_RUNNER_CHILD_ENV} is reserved for the test runner"
+    TEST_RUNNER_CHILD_ENV = EnvKeyPolicy::TEST_RUNNER_CHILD_ENV
+    RESERVED_KEY_ERROR = EnvKeyPolicy::RESERVED_KEY_ERROR
 
     # The env tools may not set or delete the test runner marker, whatever its case.
     def self.reserved_key?(key)
-      key.to_s.upcase == TEST_RUNNER_CHILD_ENV
+      EnvKeyPolicy.reserved?(key)
     end
 
+    # Runs before every Sidekiq job and console line: the file is parsed again only when it was
+    # replaced or changed since the last call (cached_overrides). Each key is applied on its own,
+    # so that a key that cannot be written leaves the others applied. A key EnvKeyPolicy refuses,
+    # or a value ENV cannot hold, written by a version that did not check them, is left out.
     def apply!
       return if ENV[TEST_RUNNER_CHILD_ENV] == "1"
       return if blocked_reason
 
-      overrides = load_overrides
-      restore_keys = []
-
-      overrides.each do |key, entry|
-        value    = entry.is_a?(Hash) ? entry["value"]    : entry
-        original = entry.is_a?(Hash) ? entry["original"] : nil
-
-        remember_process_original(key) unless value == RESTORE_SENTINEL
-
-        case value
-        when DELETED_SENTINEL
-          ENV.delete(key)
-        when RESTORE_SENTINEL
-          original.nil? ? ENV.delete(key) : ENV[key] = original
-          restore_keys << key
-        else
-          ENV[key] = value
+      skipped = []
+      cached_overrides.each do |key, entry|
+        unless applicable?(key, entry)
+          skipped << key
+          next
         end
-      end
 
-      if restore_keys.any?
-        # Read again under the lock: another writer may have changed the file since.
-        update_overrides do |current|
-          restore_keys.each do |k|
-            entry = current[k]
-            current.delete(k) if entry.is_a?(Hash) && entry["value"] == RESTORE_SENTINEL
-          end
-        end
+        apply_entry(key, entry)
+      rescue StandardError => e
+        Profiler.log_error("EnvOverrideStore: failed to apply an override", e)
       end
+      log_skipped_keys(skipped)
     rescue => e
       Profiler.log_error("EnvOverrideStore: failed to apply overrides", e)
     end
@@ -191,6 +202,72 @@ module Profiler
       raise Error, "could not #{action} in env_overrides.json under tmp_path: #{reason}"
     end
 
+    def applicable?(key, entry)
+      return false unless EnvKeyPolicy.allowed?(key)
+
+      value = entry.is_a?(Hash) ? entry["value"] : entry
+      EnvKeyPolicy.value_rejection(key, value).nil?
+    end
+
+    def apply_entry(key, entry)
+      value = entry.is_a?(Hash) ? entry["value"] : entry
+
+      if value == RESTORE_SENTINEL
+        restore_applied(key)
+        return
+      end
+
+      remember_process_original(key)
+      value == DELETED_SENTINEL ? ENV.delete(key) : ENV[key] = value
+    end
+
+    # A RESTORE entry stays in the file for every process: this one puts the key back only if it
+    # changed it, once, to the value it had before. A process that never applied the override has
+    # nothing to restore.
+    def restore_applied(key)
+      changed_here, original = @process_originals_lock.synchronize do
+        [@process_originals.key?(key), @process_originals.delete(key)]
+      end
+      return unless changed_here
+
+      original.nil? ? ENV.delete(key) : ENV[key] = original
+    end
+
+    # Says once per set of keys how many were left out, never which: the log may be shared.
+    def log_skipped_keys(skipped)
+      return if skipped.empty? || @skipped_keys_logged == skipped
+
+      @skipped_keys_logged = skipped
+      noun = skipped.size == 1 ? "override was" : "overrides were"
+      Profiler.log_warn("#{skipped.size} persisted environment #{noun} not applied: the name is not " \
+                        "a valid environment variable name, or one the profiler does not change, " \
+                        "or the value holds a NUL byte.")
+    end
+
+    def restore_entry(original)
+      { "value" => RESTORE_SENTINEL, "original" => original, "reset_at" => Time.now.to_i }
+    end
+
+    def restore_entry?(entry)
+      entry.is_a?(Hash) && entry["value"] == RESTORE_SENTINEL
+    end
+
+    # RESTORE entries older than RESTORE_TTL go when the file is next written. One written by an
+    # earlier version, with no reset_at, starts its delay now.
+    def expire_restore_entries(overrides)
+      now = Time.now.to_i
+      overrides.delete_if do |_key, entry|
+        next false unless restore_entry?(entry)
+
+        reset_at = entry["reset_at"]
+        unless reset_at.is_a?(Integer)
+          entry["reset_at"] = now
+          next false
+        end
+        now - reset_at > RESTORE_TTL
+      end
+    end
+
     def remember_process_original(key)
       @process_originals_lock.synchronize do
         @process_originals[key] = ENV[key] unless @process_originals.key?(key)
@@ -208,6 +285,11 @@ module Profiler
       return false if from_process && !changed_here
 
       original = from_process ? process_original : file_entry["original"]
+      # A name ENV cannot hold ("A=B"), written by a version that did not check the names: its
+      # entry is reset in the file, and there is nothing to put back here.
+      return false unless EnvKeyPolicy.valid_name?(key)
+      return false if EnvKeyPolicy.value_rejection(key, original)
+
       original.nil? ? ENV.delete(key) : ENV[key] = original
       true
     end
@@ -224,11 +306,46 @@ module Profiler
       path = override_file_path
       return {} unless File.exist?(path)
 
-      JSON.parse(File.read(path))
+      parse_overrides(File.read(path))
+    end
+
+    def parse_overrides(content)
+      parsed = JSON.parse(content)
+      parsed.is_a?(Hash) ? parsed : {}
     rescue JSON::ParserError
       {}
     end
 
+    # load_overrides for apply!, without reading the file again while it is the same file.
+    #
+    # The signature (inode, device, mtime, size) alone can miss a write: ext4 hands the inode the
+    # rename freed to the next temporary file, and two writes of the same size within one tick of
+    # the mtime clock then look identical, the stale value kept until the file is written again.
+    # So the content is cached only once the file has settled: its mtime at least
+    # CACHE_SETTLE_SECONDS in the past. Any later write is then at least that much younger, and
+    # gets another mtime on any file system whose mtime tick is shorter (2 seconds on FAT, the
+    # coarsest). A file written less than that ago is read at each call, which costs a read only
+    # during the seconds after a change. A write between the stat and the read caches the new
+    # content under the old signature: the next call sees another mtime and reads again.
+    def cached_overrides
+      path = override_file_path
+      stat = File.stat(path)
+      signature = [path.to_s, stat.ino, stat.dev, stat.mtime, stat.size]
+      cached = @cached_overrides
+      return cached[1] if cached && cached[0] == signature
+
+      overrides = parse_overrides(File.read(path)).freeze
+      @cached_overrides = settled?(stat) ? [signature, overrides] : nil
+      overrides
+    rescue Errno::ENOENT
+      @cached_overrides = nil
+      {}
+    end
+
+    def settled?(stat)
+      Time.now - stat.mtime >= CACHE_SETTLE_SECONDS
+    end
+
     # Reads, changes and writes the file under the lock, so that the web process, its threads and
     # the Sidekiq processes never save over each other's changes. The file is removed when the
     # block leaves it empty.
@@ -236,6 +353,7 @@ module Profiler
       with_lock do
         overrides = load_overrides
         yield overrides
+        expire_restore_entries(overrides)
         overrides.empty? ? FileUtils.rm_f(override_file_path) : save_overrides(overrides)
       end
     end

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

@@ -6,11 +6,32 @@ require_relative "http_guard"
 module Profiler
   module MCP
     class Server
+      # The tools that change the profiler's data, ENV or run code: left out when
+      # config.mcp_read_only is true or PROFILER_MCP_READ_ONLY is set (Server.read_only?).
+      WRITE_TOOLS = %w[
+        run_tests clear_profiles set_env_var delete_env_var reset_env_var reset_all_env_vars
+      ].freeze
+
+      # Makes the server read-only like config.mcp_read_only, for exe/profiler-mcp above all: that
+      # executable does not boot the application, so the application's initializers, and the
+      # option they set, never run there. Any value but an empty one, 0, false, no or off turns
+      # it on; it never turns off a config.mcp_read_only set to true.
+      READ_ONLY_ENV = "PROFILER_MCP_READ_ONLY"
+      READ_ONLY_ENV_OFF = %w[0 false no off].freeze
+
       class << self
         def instance
           @instance ||= new
         end
 
+        # Whether the server leaves out WRITE_TOOLS: config.mcp_read_only, or READ_ONLY_ENV.
+        def read_only?
+          return true if Profiler.configuration.mcp_read_only
+
+          value = ENV[READ_ONLY_ENV].to_s.strip.downcase
+          !value.empty? && !READ_ONLY_ENV_OFF.include?(value)
+        end
+
         def rack_app
           # Memoized at class level — survives route reloads in development
           @rack_app ||= lambda do |env|
@@ -155,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)" },
@@ -399,10 +420,13 @@ module Profiler
             input_schema: { properties: {} },
             handler: Tools::ListSlaves
           )
-        ]
+        ].compact
       end
 
+      # nil for a tool a read-only server leaves out (Server.read_only?); build_tools drops it.
       def define_tool(name:, description:, input_schema:, handler:)
+        return nil if WRITE_TOOLS.include?(name) && self.class.read_only?
+
         ::MCP::Tool.define(name: name, description: description, input_schema: input_schema) do |server_context: nil, **args|
           result = handler.call(args.transform_keys(&:to_s))
           result.is_a?(::MCP::Tool::Response) ? result : ::MCP::Tool::Response.new(result)

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

@@ -2,6 +2,7 @@
 
 require "mcp"
 require_relative "../slave_support"
+require_relative "../../env_key_policy"
 
 module Profiler
   module MCP
@@ -11,9 +12,11 @@ module Profiler
           key = params["key"].to_s.strip
 
           return [{ type: "text", text: "Error: key cannot be blank." }] if key.empty?
-          if Profiler::EnvOverrideStore.reserved_key?(key)
+          # Checked before the store is written, and before a slave is asked: a refused key never
+          # reaches the file nor ENV.
+          if (reason = Profiler::EnvKeyPolicy.rejection(key))
             return ::MCP::Tool::Response.new(
-              [{ type: "text", text: "Error: #{Profiler::EnvOverrideStore::RESERVED_KEY_ERROR}; #{key} was left unchanged." }],
+              [{ type: "text", text: "Error: #{reason}; #{key} was left unchanged." }],
               error: true
             )
           end

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/mcp/tools/set_env_var.rb

@@ -2,6 +2,7 @@
 
 require "mcp"
 require_relative "../slave_support"
+require_relative "../../env_key_policy"
 require_relative "../../redaction"
 
 module Profiler
@@ -13,9 +14,11 @@ module Profiler
           value = params["value"].to_s
 
           return [{ type: "text", text: "Error: key cannot be blank." }] if key.empty?
-          if Profiler::EnvOverrideStore.reserved_key?(key)
+          # Checked before the store is written, and before a slave is asked: a refused key or value
+          # never reaches the file nor ENV.
+          if (reason = Profiler::EnvKeyPolicy.rejection(key) || Profiler::EnvKeyPolicy.value_rejection(key, value))
             return ::MCP::Tool::Response.new(
-              [{ type: "text", text: "Error: #{Profiler::EnvOverrideStore::RESERVED_KEY_ERROR}; #{key} was left unchanged." }],
+              [{ type: "text", text: "Error: #{reason}; #{key} was left unchanged." }],
               error: true
             )
           end

data/lib/profiler/test_runner/runner.rb

@@ -3,6 +3,7 @@
 require "set"
 require_relative "../boot_env"
 require_relative "../env_override_store"
+require_relative "../env_key_policy"
 require_relative "run_store"
 require_relative "discovery"
 
@@ -176,26 +177,14 @@ module Profiler
         end
       end
 
-      BLOCKED_ENV_KEYS = %w[RAILS_ENV RACK_ENV DATABASE_URL SECRET_KEY_BASE PROFILER_TEST_RUNNER_CHILD].freeze
-
-      # Overrides of these variables make the test process, or the shell shims (rbenv, asdf) that
-      # start it, load or run code other than the selected tests. It is a deny list, so it cannot
-      # be complete; a variable needed by the tests can be set in the shell that starts Rails.
-      CODE_LOADING_ENV_KEYS = %w[
-        SPEC_OPTS TESTOPTS TEST PATH HOME XDG_CONFIG_HOME GEMRC NODE_OPTIONS NODE_PATH
-        SHELLOPTS BASHOPTS PS4 ENV CDPATH IFS
-      ].freeze
-      CODE_LOADING_ENV_PREFIXES = %w[
-        RUBY GEM_ BUNDLE_ BUNDLER_ LD_ DYLD_ BASH_ RBENV_ ASDF_ RVM_ CHRUBY GIT_ BOOTSNAP_
-        PYTHON PERL5
-      ].freeze
-      ENV_NAME = /\A[A-Z_][A-Z0-9_]*\z/i
+      # The lists live in Profiler::EnvKeyPolicy, shared with the Env tab and the MCP env tools.
+      BLOCKED_ENV_KEYS = EnvKeyPolicy::PROTECTED_KEYS
+      CODE_LOADING_ENV_KEYS = EnvKeyPolicy::CODE_LOADING_KEYS
+      CODE_LOADING_ENV_PREFIXES = EnvKeyPolicy::CODE_LOADING_PREFIXES
+      ENV_NAME = EnvKeyPolicy::ENV_NAME
 
       def self.code_loading_env_key?(key)
-        name = key.to_s.upcase
-        return true unless ENV_NAME.match?(name)
-
-        CODE_LOADING_ENV_KEYS.include?(name) || CODE_LOADING_ENV_PREFIXES.any? { |prefix| name.start_with?(prefix) }
+        EnvKeyPolicy.code_loading?(key)
       end
 
       # Starts from the copy of ENV taken when the gem was loaded, not from ENV: the overrides are
@@ -208,12 +197,15 @@ module Profiler
 
         overrides = Profiler.env_override_store.all_overrides
         overrides.each do |key, entry|
-          blocked = BLOCKED_ENV_KEYS.include?(key.upcase)
+          blocked = EnvKeyPolicy.protected?(key)
           if blocked || code_loading_env_key?(key)
             left_out << key unless blocked
             next
           end
           value = entry.is_a?(Hash) ? entry["value"] : entry
+          # A value the process environment cannot hold, saved by a version that did not check it.
+          next if EnvKeyPolicy.value_rejection(key, value)
+
           if value == EnvOverrideStore::DELETED_SENTINEL
             base.delete(key)
           else

data/lib/profiler/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails-profiler
 version: !ruby/object:Gem::Version
-  version: 0.33.3
+  version: 0.34.1
 platform: ruby
 authors:
 - Sébastien Duplessy
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-14 00:00:00.000000000 Z
+date: 2026-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -169,6 +169,7 @@ files:
 - lib/profiler/console_profiler.rb
 - lib/profiler/current_context.rb
 - lib/profiler/engine.rb
+- lib/profiler/env_key_policy.rb
 - lib/profiler/env_override_store.rb
 - lib/profiler/explain_runner.rb
 - lib/profiler/instrumentation/active_job_instrumentation.rb