rails-profiler 0.33.3 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 533fac499cbab38112f1be4ab7d066761f0f0cea1b22d76e4d355059ef03d9dd
-  data.tar.gz: b8d37a14501188a671be2ee4876b8ce9678641cca8acbd836e456ea62249ef48
+  metadata.gz: b6a0140a91e984bd6d06d7277a149c2a7eeace21ec53c3d3ddc1acb7eb137879
+  data.tar.gz: 730abdd8332a638e3d78db3d74378ab10fc1280f9d5f83f11b327409b076c1e3
 SHA512:
-  metadata.gz: 7daad08c5c0b6a119933341e7b1a1ba28d746c2801eef525a83dd54388c85a30bfa68a7240d2e99705992e622929df012b98676f0ec396a028fff759690910da
-  data.tar.gz: d205ba6d72f09ca00d1eb714db57f99052e64297caddb33999c8c6ae87ae380874cf015af986d0065d7b76c949388a813f3f397adae3fe23b7f5a1e6bdbcbc48
+  metadata.gz: '09a3cac5a02d3407f8a03dad19154d8f36c5dd57e8c1f5d9b0021aad015e7e459a4305592e68defb796672a9cbd29b40c48b2933cff56b2fe340c3ae370de767'
+  data.tar.gz: dda83a3c7086e4679766abe06d0dc5e88befc5e9ebebb19a87ec605a3b268a2ab81fccef0274e8170043bb4c6ab452f68307e5a1546921b55b418289427fc805

data/CHANGELOG.md

@@ -19,6 +19,50 @@ every commit of every tag interval is accounted for one way or the other.
 
 ## [Unreleased]
 
+## [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/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/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,
@@ -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

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/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|
@@ -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/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.0"
 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.0
 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