poollint 0.1.0

data/lib/poollint/execution_state.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "active_support/isolated_execution_state"
+
+module PoolLint
+  module ExecutionState
+    KEY = :poollint_inspecting
+    SUPPRESSION_KEY = :poollint_suppressed
+
+    module_function
+
+    def inspecting?
+      ActiveSupport::IsolatedExecutionState[KEY] == true
+    end
+
+    def while_inspecting
+      previous = ActiveSupport::IsolatedExecutionState[KEY]
+      ActiveSupport::IsolatedExecutionState[KEY] = true
+      yield
+    ensure
+      ActiveSupport::IsolatedExecutionState[KEY] = previous
+    end
+
+    def suppressed?
+      ActiveSupport::IsolatedExecutionState[SUPPRESSION_KEY] == true
+    end
+
+    def suppress
+      previous = ActiveSupport::IsolatedExecutionState[SUPPRESSION_KEY]
+      ActiveSupport::IsolatedExecutionState[SUPPRESSION_KEY] = true
+      yield
+    ensure
+      ActiveSupport::IsolatedExecutionState[SUPPRESSION_KEY] = previous
+    end
+  end
+end

data/lib/poollint/hooks/checkin_hook.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module PoolLint
+  module Hooks
+    module CheckinHook
+      module_function
+
+      # Active Record invokes this while holding the pool mutex. This inspection
+      # point is intended for tests and controlled environments, not production.
+      def call(connection)
+        InspectionRunner.call(connection, :checkin)
+      end
+    end
+  end
+end

data/lib/poollint/hooks/checkout_hook.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module PoolLint
+  module Hooks
+    module CheckoutHook
+      module_function
+
+      def call(connection)
+        InspectionRunner.call(connection, :checkout)
+      end
+    end
+  end
+end

data/lib/poollint/hooks/lifecycle.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module PoolLint
+  module Hooks
+    module Lifecycle
+      def discard!
+        ConnectionState.remove(self)
+        super
+      end
+
+      def reconnect!(...)
+        super.tap { ConnectionState.remove(self) }
+      end
+    end
+  end
+end

data/lib/poollint/hooks.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module PoolLint
+  module Hooks
+    CHECKOUT_CALLBACK = proc { |connection| CheckoutHook.call(connection) }
+    CHECKIN_CALLBACK = proc { |connection| CheckinHook.call(connection) }
+
+    class << self
+      def install!
+        return if @installed
+
+        adapter = ActiveRecord::ConnectionAdapters::AbstractAdapter
+        adapter.prepend(Lifecycle)
+        install_callbacks(adapter)
+        @installed = true
+      end
+
+      private
+
+      def install_callbacks(adapter)
+        adapter.set_callback(:checkout, :after, CHECKOUT_CALLBACK)
+        adapter.set_callback(:checkin, :before, CHECKIN_CALLBACK)
+      end
+    end
+  end
+end

data/lib/poollint/inspection_runner.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module PoolLint
+  class InspectionRunner
+    class << self
+      def call(connection, inspection_point)
+        configuration = PoolLint.configuration
+        inspector_class = Inspectors.for(connection)
+        return unless inspector_class
+
+        state = PoolLint.connection_state(connection)
+        establish_baseline(inspector_class, connection, state, configuration)
+        return unless configuration.inspection_point == inspection_point
+        return unless state.dirty?
+        return if rand >= configuration.check_probability
+
+        inspect_and_notify(connection, state, inspection_point, configuration, inspector_class)
+      rescue LeakDetected
+        raise
+      rescue StandardError => e
+        PoolLint.log_warning(
+          "inspection skipped after #{e.class}: #{e.message}"
+        )
+      end
+
+      private
+
+      def establish_baseline(inspector_class, connection, state, configuration)
+        return if state.baseline?
+
+        inspector_class.new(configuration).establish_baseline(connection, state)
+      end
+
+      def inspect_and_notify(connection, state, inspection_point, configuration, inspector_class)
+        inspector = inspector_class.new(configuration)
+        report = inspector.inspect(connection, state, inspection_point: inspection_point)
+        Notifier.new(configuration).call(report) if report
+      end
+    end
+  end
+end

data/lib/poollint/inspectors/mysql.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module PoolLint
+  module Inspectors
+    class MySQL
+      Snapshot = Struct.new(:settings, :user_level_locks, keyword_init: true)
+      class PerformanceSchemaUnavailable < StandardError; end
+
+      SETTING_NAME = /\A[a-z_][a-z0-9_]*\z/
+
+      INSTRUMENT_SQL = <<~SQL
+        SELECT /*+ MAX_EXECUTION_TIME(%<timeout_ms>d) */ COUNT(*)
+          FROM performance_schema.setup_instruments
+         WHERE NAME = 'wait/lock/metadata/sql/mdl'
+           AND ENABLED = 'YES'
+      SQL
+
+      USER_LOCKS_SQL = <<~SQL
+        SELECT /*+ MAX_EXECUTION_TIME(%<timeout_ms>d) */
+               ml.OBJECT_NAME AS name,
+               ml.LOCK_TYPE AS mode,
+               ml.LOCK_STATUS AS status
+          FROM performance_schema.metadata_locks ml
+          JOIN performance_schema.threads t
+            ON t.THREAD_ID = ml.OWNER_THREAD_ID
+         WHERE ml.OBJECT_TYPE = 'USER LEVEL LOCK'
+           AND ml.LOCK_STATUS = 'GRANTED'
+           AND t.PROCESSLIST_ID = CONNECTION_ID()
+         ORDER BY ml.OBJECT_NAME
+      SQL
+
+      def initialize(configuration)
+        @configuration = configuration
+        @allowed_settings = AllowedSettings.new(configuration.allowed_settings)
+      end
+
+      def establish_baseline(connection, state)
+        snapshot = capture_snapshot(connection, state)
+        state.capture_baseline(snapshot)
+        ConnectionState.attach(connection, state)
+        snapshot
+      end
+
+      def inspect(connection, state, inspection_point:)
+        baseline = state.baseline
+        return establish_baseline(connection, state) unless baseline
+        return unless state.dirty?
+
+        snapshot = capture_snapshot(connection, state)
+        unless state_attached?(connection, state)
+          return reattach_after_reconnect(connection, state, snapshot)
+        end
+
+        report = build_report(baseline, snapshot, state, inspection_point)
+        state.finish_inspection(
+          snapshot: snapshot,
+          rebaseline: report.leak? && @configuration.rebaseline_after_report
+        )
+        report if report.leak?
+      end
+
+      private
+
+      def build_report(baseline, snapshot, state, inspection_point)
+        Report.new(
+          inspection_point: inspection_point,
+          setting_changes: setting_changes(baseline, snapshot),
+          advisory_locks: [],
+          user_level_locks: user_lock_changes(baseline, snapshot),
+          suspicions: state.suspicions
+        )
+      end
+
+      def capture_confirmed_user_locks(connection)
+        sql = format(INSTRUMENT_SQL, timeout_ms: inspection_timeout_ms)
+        enabled = connection.select_value(sql, "PoolLint")
+        if enabled.to_i.zero?
+          raise PerformanceSchemaUnavailable, "metadata lock instrument is disabled"
+        end
+
+        locks_sql = format(USER_LOCKS_SQL, timeout_ms: inspection_timeout_ms)
+        connection.select_all(locks_sql, "PoolLint").map do |row|
+          UserLevelLock.new(
+            name: row.fetch("name"),
+            mode: row["mode"],
+            status: row["status"],
+            confidence: :confirmed
+          )
+        end
+      end
+
+      def capture_settings(connection)
+        names = @configuration.mysql_watched_settings
+        validate_setting_names!(names)
+        selections = names.map do |name|
+          "@@SESSION.#{name} AS #{connection.quote_column_name(name)}"
+        end
+        sql = "SELECT /*+ MAX_EXECUTION_TIME(#{inspection_timeout_ms}) */ #{selections.join(', ')}"
+        connection.select_one(sql, "PoolLint").to_h do |name, value|
+          [name, value.to_s]
+        end
+      end
+
+      def capture_snapshot(connection, state)
+        ExecutionState.while_inspecting do
+          Snapshot.new(
+            settings: capture_settings(connection),
+            user_level_locks: capture_user_locks(connection, state)
+          )
+        end
+      end
+
+      def capture_user_locks(connection, state)
+        capture_confirmed_user_locks(connection)
+      rescue StandardError => e
+        PoolLint.log_warning(
+          "MySQL user-level lock inspection is inferred after #{e.class}: #{e.message}"
+        )
+        inferred_user_locks(state)
+      end
+
+      def inferred_user_locks(state)
+        state.inferred_user_locks.map do |name, count|
+          UserLevelLock.new(name: name, acquisition_count: count, confidence: :inferred)
+        end
+      end
+
+      def inspection_timeout_ms
+        (@configuration.inspection_timeout * 1000).ceil
+      end
+
+      def reattach_after_reconnect(connection, state, snapshot)
+        state.capture_baseline(snapshot)
+        ConnectionState.attach(connection, state)
+        nil
+      end
+
+      def setting_changes(baseline, snapshot)
+        names = baseline.settings.keys | snapshot.settings.keys
+        names.filter_map do |name|
+          expected = baseline.settings[name]
+          current = snapshot.settings[name]
+          next if expected == current
+          next if @allowed_settings.allow?(name, current)
+
+          SettingChange.new(
+            name: name,
+            baseline: expected,
+            current: current,
+            comparison: :baseline
+          )
+        end
+      end
+
+      def state_attached?(connection, state)
+        ConnectionState.attached?(connection, state)
+      end
+
+      def user_lock_changes(baseline, snapshot)
+        baseline_fingerprints = baseline.user_level_locks.map(&:fingerprint)
+        snapshot.user_level_locks.reject do |lock|
+          baseline_fingerprints.include?(lock.fingerprint)
+        end
+      end
+
+      def validate_setting_names!(names)
+        invalid = names.grep_v(SETTING_NAME)
+        return if invalid.empty?
+
+        raise ArgumentError, "invalid MySQL session variables: #{invalid.join(', ')}"
+      end
+    end
+  end
+end

data/lib/poollint/inspectors/postgresql.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module PoolLint
+  module Inspectors
+    class PostgreSQL
+      SPECIAL_SETTINGS = %w[role session_authorization].freeze
+      Snapshot = Struct.new(:settings, :advisory_locks, keyword_init: true)
+      SettingValue = Struct.new(:setting, :reset_value, keyword_init: true)
+
+      SETTINGS_SQL = <<~SQL
+        WITH requested(name) AS (
+          SELECT unnest(ARRAY[%<settings>s]::text[])
+        )
+        SELECT requested.name,
+               current_setting(requested.name, true) AS setting,
+               pg_settings.reset_val
+          FROM requested
+          LEFT JOIN pg_settings ON pg_settings.name = requested.name
+         ORDER BY requested.name
+      SQL
+
+      ADVISORY_LOCKS_SQL = <<~SQL
+        SELECT database::text,
+               classid::text,
+               objid::text,
+               objsubid,
+               mode
+          FROM pg_locks
+         WHERE locktype = 'advisory'
+           AND pid = pg_backend_pid()
+           AND granted
+         ORDER BY database, classid, objid, objsubid, mode
+      SQL
+
+      def initialize(configuration)
+        @configuration = configuration
+        @allowed_settings = AllowedSettings.new(configuration.allowed_settings)
+        @capture = PostgreSQLCapture.new(configuration)
+      end
+
+      def establish_baseline(connection, state)
+        snapshot = capture_with_timeout(connection, settings_for(state))
+        state.capture_baseline(snapshot)
+        ConnectionState.attach(connection, state)
+        snapshot
+      end
+
+      def inspect(connection, state, inspection_point:)
+        baseline = state.baseline
+        return establish_baseline(connection, state) unless baseline
+        return unless state.dirty?
+
+        snapshot = capture_with_timeout(connection, settings_for(state, baseline))
+        unless state_attached?(connection, state)
+          return reattach_after_reconnect(connection, state, snapshot)
+        end
+
+        report = build_report(baseline, snapshot, state, inspection_point)
+        state.finish_inspection(
+          snapshot: snapshot,
+          rebaseline: report.leak? && @configuration.rebaseline_after_report
+        )
+        report if report.leak?
+      end
+
+      private
+
+      def advisory_lock_changes(baseline, snapshot)
+        baseline_fingerprints = baseline.advisory_locks.map(&:fingerprint)
+        snapshot.advisory_locks.reject do |lock|
+          baseline_fingerprints.include?(lock.fingerprint)
+        end
+      end
+
+      def build_report(baseline, snapshot, state, inspection_point)
+        Report.new(
+          inspection_point: inspection_point,
+          setting_changes: setting_changes(baseline, snapshot),
+          advisory_locks: advisory_lock_changes(baseline, snapshot),
+          suspicions: state.suspicions
+        )
+      end
+
+      def capture_advisory_locks(connection)
+        return [] unless @configuration.check_advisory_locks
+
+        connection.select_all(ADVISORY_LOCKS_SQL, "PoolLint").map do |row|
+          AdvisoryLock.new(
+            database: row["database"],
+            class_id: row["classid"],
+            object_key: row["objid"],
+            object_sub_id: row["objsubid"].to_i,
+            mode: row["mode"]
+          ).tap do |lock|
+            lock.human_name = KannukiLockResolver.name_for(lock)
+          end
+        end
+      end
+
+      def capture_settings(connection, names)
+        quoted_names = names.map { |name| connection.quote(name) }.join(", ")
+        sql = format(SETTINGS_SQL, settings: quoted_names)
+        connection.select_all(sql, "PoolLint").to_h do |row|
+          [
+            row.fetch("name"),
+            SettingValue.new(setting: row["setting"], reset_value: row["reset_val"])
+          ]
+        end
+      end
+
+      def capture_snapshot(connection, names)
+        Snapshot.new(
+          settings: capture_settings(connection, names),
+          advisory_locks: capture_advisory_locks(connection)
+        )
+      end
+
+      def capture_with_timeout(connection, names)
+        @capture.call(connection, names) { capture_snapshot(connection, names) }
+      end
+
+      def comparison_for(name, baseline_value, current_value)
+        return baseline_comparison(name, baseline_value, current_value) if baseline_value
+
+        reset_comparison(name, current_value)
+      end
+
+      def baseline_comparison(name, baseline_value, current_value)
+        return if baseline_value.setting == current_value.setting
+
+        SettingChange.new(
+          name: name,
+          baseline: baseline_value.setting,
+          current: current_value.setting,
+          reset_value: current_value.reset_value,
+          comparison: :baseline
+        )
+      end
+
+      def reset_comparison(name, current_value)
+        reset_value = current_value.reset_value
+        reset_value = "" if reset_value.nil?
+        return if current_value.setting.to_s == reset_value.to_s
+
+        SettingChange.new(
+          name: name,
+          baseline: nil,
+          current: current_value.setting,
+          reset_value: reset_value,
+          comparison: :reset_value
+        )
+      end
+
+      def reattach_after_reconnect(connection, state, snapshot)
+        state.capture_baseline(snapshot)
+        ConnectionState.attach(connection, state)
+        nil
+      end
+
+      def setting_changes(baseline, snapshot)
+        names = baseline.settings.keys | snapshot.settings.keys
+        names.filter_map do |name|
+          current = snapshot.settings.fetch(name, SettingValue.new)
+          change = comparison_for(name, baseline.settings[name], current)
+          change unless change && @allowed_settings.allow?(name, change.current)
+        end
+      end
+
+      def state_attached?(connection, state)
+        ConnectionState.attached?(connection, state)
+      end
+
+      def settings_for(state, baseline = nil)
+        (
+          SPECIAL_SETTINGS +
+          @configuration.watched_settings +
+          state.monitored_settings +
+          Array(baseline&.settings&.keys)
+        ).compact.map(&:downcase).uniq
+      end
+    end
+  end
+end

data/lib/poollint/inspectors/postgresql_capture.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module PoolLint
+  module Inspectors
+    class PostgreSQLCapture
+      def initialize(configuration)
+        @configuration = configuration
+      end
+
+      def call(connection, names)
+        snapshot = nil
+        ExecutionState.while_inspecting do
+          connection.transaction(requires_new: true, joinable: false) do
+            original_timeout = capture_statement_timeout(connection, names)
+            apply_timeout(connection)
+            snapshot = yield
+            restore_statement_timeout(snapshot, original_timeout)
+            raise ActiveRecord::Rollback
+          end
+        end
+        snapshot
+      rescue StandardError => e
+        raise InspectionTimeout, "inspection exceeded statement_timeout" if query_canceled?(e)
+
+        raise
+      end
+
+      private
+
+      def apply_timeout(connection)
+        timeout_ms = (@configuration.inspection_timeout * 1000).ceil
+        connection.execute("SET LOCAL statement_timeout = #{timeout_ms}")
+      end
+
+      def capture_statement_timeout(connection, names)
+        return unless names.include?("statement_timeout")
+
+        connection.select_value("SELECT current_setting('statement_timeout')")
+      end
+
+      def query_canceled?(error)
+        active_record_timeout = defined?(ActiveRecord::QueryCanceled) &&
+                                error.is_a?(ActiveRecord::QueryCanceled)
+        active_record_timeout || error.cause&.class&.name == "PG::QueryCanceled"
+      end
+
+      def restore_statement_timeout(snapshot, original_timeout)
+        return unless original_timeout
+
+        captured = snapshot.settings.fetch("statement_timeout")
+        snapshot.settings["statement_timeout"] = captured.class.new(
+          setting: original_timeout,
+          reset_value: captured.reset_value
+        )
+      end
+    end
+  end
+end

data/lib/poollint/inspectors.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module PoolLint
+  module Inspectors
+    MYSQL_ADAPTERS = %w[Mysql2 Trilogy].freeze
+
+    module_function
+
+    def for(connection)
+      return PostgreSQL if connection.adapter_name == "PostgreSQL"
+      return MySQL if MYSQL_ADAPTERS.include?(connection.adapter_name)
+
+      nil
+    end
+  end
+end

data/lib/poollint/kannuki_lock_resolver.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module PoolLint
+  module KannukiLockResolver
+    module_function
+
+    def name_for(lock)
+      return unless defined?(::Kannuki::LockKey) && defined?(::Kannuki::LockManager)
+
+      ::Kannuki::LockManager.current_locks.find do |name|
+        ::Kannuki::LockKey.new(name).numeric_key == lock.numeric_key
+      end
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/poollint/notifier.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module PoolLint
+  class Notifier
+    EVENT_NAME = "leaked_state.poollint"
+
+    def initialize(configuration)
+      @configuration = configuration
+    end
+
+    def call(report)
+      return if ExecutionState.suppressed?
+      return if @configuration.ignore_if&.call(report)
+
+      ActiveSupport::Notifications.instrument(EVENT_NAME, report.to_h)
+
+      raise LeakedSessionState, report if @configuration.mode == :raise
+
+      PoolLint.log_warning(report.to_s)
+    end
+  end
+end

data/lib/poollint/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module PoolLint
+  class Railtie < Rails::Railtie
+    initializer "poollint.install" do
+      PoolLint.install!
+    end
+  end
+end