rails-profiler 0.33.2 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e1caccb1662a8f09108682f5933e943d41a0b36ed7d60930c60eb8c385b5159
-  data.tar.gz: c10d767853cc07caa36484f9693a4c4adeef415e0874d29ca817d8d7d1b17730
+  metadata.gz: b6a0140a91e984bd6d06d7277a149c2a7eeace21ec53c3d3ddc1acb7eb137879
+  data.tar.gz: 730abdd8332a638e3d78db3d74378ab10fc1280f9d5f83f11b327409b076c1e3
 SHA512:
-  metadata.gz: 8aacfc0469f52d9f6a11a58356eebb853ff716f2729ca47833b9b0ca99197f767a0dad5904f8c9e7d8a8501869dd712a0c5e6e246fa8ea0e55976b546589d1ac
-  data.tar.gz: 3ce33e8db95c0ae4028a68e11d941bb72072b5a6edcf539cfc0fb918c2248d675c4df92e28788da0d59d942546458384b22ec5ac974bb58404be1d0049130627
+  metadata.gz: '09a3cac5a02d3407f8a03dad19154d8f36c5dd57e8c1f5d9b0021aad015e7e459a4305592e68defb796672a9cbd29b40c48b2933cff56b2fe340c3ae370de767'
+  data.tar.gz: dda83a3c7086e4679766abe06d0dc5e88befc5e9ebebb19a87ec605a3b268a2ab81fccef0274e8170043bb4c6ab452f68307e5a1546921b55b418289427fc805

data/CHANGELOG.md

@@ -19,6 +19,79 @@ 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 -->
+
+### Fixed
+
+- **Rake tasks:** `rake profiler:cleanup` with an empty or non-numeric `OLDER_THAN` (`""`,
+  `abc`) no longer removes every profile, and `OLDER_THAN=1h` is no longer read as one second.
+  `OLDER_THAN` and `LIMIT` take a whole number only; any other value stops the task with an error
+  and removes nothing. `OLDER_THAN=0` still removes every profile, when written so.
+- **Storage:** The SQLite store compares the start times of the profiles in UTC. Outside UTC,
+  `rake profiler:cleanup` and `cleanup` removed recent profiles (America/New_York) or kept old
+  ones (Asia/Tokyo), and the lists were out of order across a clock change. The profiles already
+  in the database are converted once, when the store opens it; the API shows the same times.
+- **Storage:** The Redis store takes expired profiles out of its lists at each save, and its list
+  keys now expire a TTL after the last save. Without `max_profiles`, or between two evictions,
+  the tokens of expired profiles stayed listed until a manual cleanup, and a page of the list
+  came back with fewer profiles than asked.
+- **Storage:** With the SQLite store, a profile saved again without a response body no longer
+  shows the response body of its previous save. The response bodies left on disk by profiles
+  removed outside the store are removed by `cleanup` and when the oldest profiles are evicted.
+
+### Limitations
+
+- **Storage:** Two SQLite stores that share a `blob_path` remove each other's response bodies:
+  give each `database` its own `blob_path` (see `docs/storage.md`).
+- **Storage:** On the first save after an upgrade, the Redis store can drop from its lists a job
+  that started more than a TTL ago and was saved recently. It happens once.
+
 ## [0.33.2] - 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/storage/blob_store.rb

@@ -2,6 +2,7 @@
 
 require "fileutils"
 require "json"
+require "set"
 require_relative "private_files"
 require_relative "token"
 
@@ -12,6 +13,8 @@ module Profiler
     # find nothing and writes are refused.
     class BlobStore
       NAME_FORMAT = /\A[a-z0-9_]+\z/
+      # A save writes its blobs before its row: prune leaves the directories this recent alone.
+      PRUNE_GRACE = 60
 
       def initialize(path)
         @path = path.to_s
@@ -46,6 +49,36 @@ module Profiler
         FileUtils.rm_rf(dir) if File.directory?(dir)
       end
 
+      # Removes one blob of token, and its directory once it holds no other.
+      def delete_blob(token, collector_name)
+        return unless valid?(token, collector_name)
+
+        dir = token_dir(token)
+        FileUtils.rm_f(File.join(dir, "#{collector_name}.json"))
+        Dir.rmdir(dir) if File.directory?(dir) && Dir.empty?(dir)
+      rescue SystemCallError => e
+        Profiler.log_error("BlobStore: could not delete #{token}/#{collector_name}", e)
+      end
+
+      # Removes the directories of the tokens not in except_tokens: those whose row was deleted
+      # outside the store, or that a failed save left behind. Only the directories named as a
+      # token and unchanged for grace seconds are considered.
+      def prune(except_tokens, grace: PRUNE_GRACE)
+        keep = except_tokens.to_set
+        cutoff = Time.now - grace
+        Dir.each_child(@path) do |name|
+          next if !Token.valid?(name) || keep.include?(name)
+
+          dir = token_dir(name)
+          stat = File.lstat(dir)
+          FileUtils.rm_rf(dir) if stat.directory? && stat.mtime < cutoff
+        rescue SystemCallError => e
+          Profiler.log_error("BlobStore: could not prune #{name}", e)
+        end
+      rescue SystemCallError => e
+        Profiler.log_error("BlobStore: could not prune #{@path}", e)
+      end
+
       def exists?(token, collector_name)
         return false unless valid?(token, collector_name)
 

data/lib/profiler/storage/redis_store.rb

@@ -28,6 +28,9 @@ module Profiler
       # of an earlier version) is removed by one process, under a lock, by batches of INDEX_BATCH.
       EVICT_BATCH = 100
       EVICT_LOCK_SECONDS = 60
+      # A page that held expired profiles is read again, once they are out of the indexes, at
+      # most this many times.
+      LIST_REPAIRS = 3
       # Deletes a lock only while it still holds the value its owner set: one that expired and was
       # taken by another process is left to it.
       RELEASE_LOCK = <<~LUA
@@ -50,7 +53,8 @@ module Profiler
         data = profile.to_h
         unindex(token, read_summary(token))
         @redis.setex(profile_key(token), @ttl, data.to_json)
-        index(token, profile.started_at.to_f, Summary.build(data))
+        @redis.pipelined { |pipe| index(token, profile.started_at.to_f, Summary.build(data), client: pipe) }
+        prune_expired
         evict_first_saved(token)
         token
       end
@@ -68,19 +72,18 @@ module Profiler
         nil
       end
 
-      # Newest first. summary: true reads the summaries only.
+      # Newest first. summary: true reads the summaries only. The profiles found expired are taken
+      # out of the indexes and the page read again, for it to hold limit profiles when there are.
       def list(limit: 50, offset: 0, type: nil, summary: false)
         ensure_index
-        tokens = @redis.zrevrange(type ? type_list_key(type) : list_key, offset, offset + limit - 1)
-        return tokens.filter_map { |token| load(token) } unless summary
+        key = type ? type_list_key(type) : list_key
+        LIST_REPAIRS.times do
+          page, expired = list_page(key, offset, limit, summary)
+          return page if expired.empty?
 
-        summaries = tokens.empty? ? [] : @redis.mget(*tokens.map { |token| summary_key(token) })
-        tokens.zip(summaries).filter_map do |token, json|
-          next Summary.to_profile(JSON.parse(json)) if json
-
-          profile = load(token)
-          profile && Summary.to_profile(Summary.build(profile))
+          remove_tokens(expired)
         end
+        list_page(key, offset, limit, summary).first
       end
 
       def cleanup(older_than: 24 * 60 * 60)
@@ -118,6 +121,46 @@ module Profiler
         Redis.new(url: url)
       end
 
+      # The page at offset, and the tokens of it whose profile has expired.
+      def list_page(key, offset, limit, summary)
+        tokens = @redis.zrevrange(key, offset, offset + limit - 1)
+        return [[], []] if tokens.empty?
+
+        expired = []
+        page = if summary
+          summaries = @redis.mget(*tokens.map { |token| summary_key(token) })
+          tokens.zip(summaries).filter_map do |token, json|
+            next Summary.to_profile(JSON.parse(json)) if json
+
+            profile = load(token)
+            expired << token if profile.nil? && !@redis.exists?(profile_key(token))
+            profile && Summary.to_profile(Summary.build(profile))
+          end
+        else
+          profiles = @redis.mget(*tokens.map { |token| profile_key(token) })
+          tokens.zip(profiles).filter_map do |token, json|
+            if json.nil?
+              expired << token
+              next
+            end
+
+            Models::Profile.from_json(json)
+          rescue => e
+            Profiler.log_error("RedisStore: could not load profile #{token}", e)
+            nil
+          end
+        end
+        [page, expired]
+      end
+
+      # A profile expires a TTL after its last save, with its keys, and Redis says nothing to the
+      # indexes: the tokens saved before that are taken out of them at each save. The indexes
+      # themselves expire a TTL after the last save, when every profile they list has.
+      def prune_expired
+        expired = @redis.zrangebyscore(saved_key, "-inf", Time.now.to_f - @ttl)
+        expired.each_slice(INDEX_BATCH) { |tokens| remove_tokens(tokens) }
+      end
+
       # score: the start time, the order of the lists. saved_at: the order of the saves, which the
       # eviction follows.
       def index(token, score, summary, saved_at: Time.now.to_f, client: @redis)
@@ -128,6 +171,7 @@ module Profiler
         client.zadd(type_list_key(type), score, token)
         client.zadd(saved_key, saved_at, token)
         client.sadd(types_key, type)
+        [list_key, type_list_key(type), saved_key, types_key].each { |key| client.expire(key, @ttl) }
         return unless Token.valid?(parent)
 
         client.sadd(children_key(parent), token)

data/lib/profiler/storage/sqlite_store.rb

@@ -2,6 +2,7 @@
 
 require "json"
 require "fileutils"
+require "time"
 require_relative "base_store"
 require_relative "blob_store"
 require_relative "private_files"
@@ -14,6 +15,7 @@ module Profiler
     class SqliteStore < BaseStore
       # Past max_profiles, the oldest profiles are evicted down to this share of it.
       LOW_WATER = 0.8
+      HTTP_BODIES = "http_response_bodies"
 
       def initialize(options = {})
         require "sqlite3"
@@ -40,13 +42,14 @@ module Profiler
         data = profile.to_h
 
         collectors_meta = {}
+        bodies_saved = false
         (data[:collectors_data] || {}).each do |collector_name, collector_data|
           next unless collector_data.is_a?(Hash)
 
           if collector_name.to_s == "http"
             requests = collector_data["requests"]
             if requests
-              stripped = save_http_response_bodies(token, requests)
+              stripped, bodies_saved = save_http_response_bodies(token, requests)
               collectors_meta[collector_name] = collector_data.merge("requests" => stripped)
             else
               collectors_meta[collector_name] = collector_data
@@ -55,6 +58,9 @@ module Profiler
             collectors_meta[collector_name] = collector_data
           end
         end
+        # A profile saved again without response bodies keeps none of its previous save: they
+        # would be merged into its requests on load.
+        @blob_store.delete_blob(token, HTTP_BODIES) unless bodies_saved
 
         @db.execute(
           <<~SQL,
@@ -76,8 +82,8 @@ module Profiler
           status:           data[:status],
           duration:         data[:duration],
           memory:           data[:memory],
-          started_at:       data[:started_at],
-          finished_at:      data[:finished_at],
+          started_at:       utc_iso8601(data[:started_at]),
+          finished_at:      utc_iso8601(data[:finished_at]),
           parent_token:     data[:parent_token],
           is_ajax:          data[:is_ajax] ? 1 : 0,
           tabs:             JSON.generate(data[:tabs] || []),
@@ -157,6 +163,7 @@ module Profiler
         ).map { |r| r["token"] }
         @db.execute("DELETE FROM profiler_profiles WHERE started_at < :cutoff", cutoff: cutoff)
         tokens.each { |token| @blob_store.delete(token) }
+        prune_blobs
       end
 
       private
@@ -179,6 +186,12 @@ module Profiler
           @db.execute("DELETE FROM profiler_profiles WHERE token IN (#{(["?"] * slice.size).join(",")})", slice)
         end
         tokens.each { |token| @blob_store.delete(token) }
+        prune_blobs
+      end
+
+      # The blobs of the rows deleted outside the store (a database removed or recreated).
+      def prune_blobs
+        @blob_store.prune(@db.execute("SELECT token FROM profiler_profiles").map { |r| r["token"] })
       end
 
       # A row written before the summary column falls back to the whole row, summarized.
@@ -195,24 +208,26 @@ module Profiler
         nil
       end
 
+      # The requests without their response bodies, and whether a blob of bodies was written.
       def save_http_response_bodies(token, requests)
         bodies = requests.map do |req|
           { "response_body" => req["response_body"], "response_body_encoding" => req["response_body_encoding"] }
         end
 
-        return requests unless bodies.any? { |b| !b["response_body"].nil? }
+        return [requests, false] unless bodies.any? { |b| !b["response_body"].nil? }
 
-        @blob_store.write(token, "http_response_bodies", bodies)
+        @blob_store.write(token, HTTP_BODIES, bodies)
 
-        requests.map do |req|
+        stripped = requests.map do |req|
           req.reject { |k, _| %w[response_body response_body_encoding].include?(k) }
         end
+        [stripped, true]
       end
 
       def load_http_response_bodies(token, requests)
         return requests if requests.nil? || requests.empty?
 
-        bodies = @blob_store.read(token, "http_response_bodies")
+        bodies = @blob_store.read(token, HTTP_BODIES)
         return requests if bodies.nil? || bodies.empty?
 
         requests.each_with_index.map do |req, i|
@@ -266,6 +281,26 @@ module Profiler
         rescue SQLite3::Exception
           # column already exists
         end
+
+        migrate_times_to_utc
+      end
+
+      # Version 1 stores the times in UTC. The rows written before it carry the local offset of
+      # the process that saved them, and the default database outlives a restart: they are
+      # rewritten once, by SQLite, which reads the offset. A value it cannot read is left as is.
+      def migrate_times_to_utc
+        return if @db.get_first_value("PRAGMA user_version").to_i >= 1
+
+        @db.transaction do
+          %w[started_at finished_at].each do |column|
+            @db.execute(<<~SQL)
+              UPDATE profiler_profiles
+                 SET #{column} = strftime('%Y-%m-%dT%H:%M:%SZ', #{column})
+               WHERE #{column} NOT LIKE '%Z' AND strftime('%Y-%m-%dT%H:%M:%SZ', #{column}) IS NOT NULL
+            SQL
+          end
+          @db.execute("PRAGMA user_version = 1")
+        end
       end
 
       def row_to_profile(row, load_blobs: true)
@@ -293,8 +328,8 @@ module Profiler
           status:                 row["status"],
           duration:               row["duration"],
           memory:                 row["memory"],
-          started_at:             row["started_at"],
-          finished_at:            row["finished_at"],
+          started_at:             local_iso8601(row["started_at"]),
+          finished_at:            local_iso8601(row["finished_at"]),
           parent_token:           row["parent_token"],
           is_ajax:                row["is_ajax"] == 1,
           tabs:                   parse_json(row["tabs"], []),
@@ -312,6 +347,25 @@ module Profiler
         nil
       end
 
+      # The times are stored in UTC, all in the same form, for the cleanup and the lists to compare
+      # them as text; a profile gives them with the offset of the process that recorded it.
+      def utc_iso8601(value)
+        return value if value.nil?
+
+        Time.iso8601(value.to_s).utc.iso8601
+      rescue ArgumentError
+        value
+      end
+
+      # Read back in local time, as the profile gave them.
+      def local_iso8601(value)
+        return value if value.nil?
+
+        Time.iso8601(value).localtime.iso8601
+      rescue ArgumentError
+        value
+      end
+
       def parse_json(value, default)
         return default if value.nil? || value.empty?
 

data/lib/profiler/tasks/profiler.rake

@@ -1,17 +1,33 @@
 # frozen_string_literal: true
 
+module Profiler
+  module Tasks
+    # The whole number an environment variable gives, or default when it is not set. An empty or
+    # non-numeric value ("", "abc", "1h") stops the task: read as 0, OLDER_THAN would delete every
+    # profile.
+    def self.integer_env(name, default, minimum:, unit:)
+      value = ENV[name]
+      return default if value.nil?
+      return Integer(value, 10) if value.match?(/\A\d+\z/) && Integer(value, 10) >= minimum
+
+      warn "#{name} must be a whole number of #{unit} (#{minimum} or more), got #{value.inspect}."
+      exit 1
+    end
+  end
+end
+
 namespace :profiler do
-  desc "Clean up old profiles"
+  desc "Clean up old profiles (OLDER_THAN: seconds, 86400 by default)"
   task cleanup: :environment do
-    older_than = ENV["OLDER_THAN"]&.to_i || 24 * 60 * 60
+    older_than = Profiler::Tasks.integer_env("OLDER_THAN", 24 * 60 * 60, minimum: 0, unit: "seconds")
     puts "Cleaning up profiles older than #{older_than} seconds..."
     Profiler.storage.cleanup(older_than: older_than)
     puts "Cleanup complete!"
   end
 
-  desc "List recent profiles"
+  desc "List recent profiles (LIMIT: 20 by default)"
   task list: :environment do
-    limit = ENV["LIMIT"]&.to_i || 20
+    limit = Profiler::Tasks.integer_env("LIMIT", 20, minimum: 1, unit: "profiles")
     profiles = Profiler.storage.list(limit: limit)
 
     if profiles.empty?

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.2"
+  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.2
+  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