poollint 0.1.0

data/lib/poollint/report.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module PoolLint
+  SettingChange = Struct.new(
+    :name,
+    :baseline,
+    :current,
+    :reset_value,
+    :comparison,
+    keyword_init: true
+  )
+
+  AdvisoryLock = Struct.new(
+    :database,
+    :class_id,
+    :object_key,
+    :object_sub_id,
+    :mode,
+    :human_name,
+    keyword_init: true
+  ) do
+    def fingerprint
+      [database, class_id, object_key, object_sub_id, mode]
+    end
+
+    def numeric_key
+      (class_id.to_i << 32) | object_key.to_i
+    end
+  end
+
+  UserLevelLock = Struct.new(
+    :name,
+    :acquisition_count,
+    :mode,
+    :status,
+    :confidence,
+    keyword_init: true
+  ) do
+    def fingerprint
+      [name, mode, status]
+    end
+  end
+
+  class Report
+    attr_reader :advisory_locks,
+                :inspection_point,
+                :setting_changes,
+                :suspicions,
+                :user_level_locks
+
+    def initialize(
+      inspection_point:,
+      setting_changes:,
+      advisory_locks:,
+      suspicions:,
+      user_level_locks: []
+    )
+      @inspection_point = inspection_point
+      @setting_changes = setting_changes
+      @advisory_locks = advisory_locks
+      @suspicions = suspicions
+      @user_level_locks = user_level_locks
+    end
+
+    def leak?
+      setting_changes.any? || advisory_locks.any? || user_level_locks.any?
+    end
+
+    def to_h
+      {
+        inspection_point: inspection_point,
+        setting_changes: setting_changes.map(&:to_h),
+        advisory_locks: advisory_locks.map(&:to_h),
+        user_level_locks: user_level_locks.map(&:to_h),
+        suspicions: suspicions.map(&:to_h)
+      }
+    end
+
+    def to_s
+      lines = [
+        "PoolLint::LeakedSessionState",
+        "",
+        boundary_message
+      ]
+      append_setting_changes(lines)
+      append_advisory_locks(lines)
+      append_user_level_locks(lines)
+      append_suspicions(lines)
+      append_remediation(lines)
+      lines.join("\n")
+    end
+
+    private
+
+    def append_advisory_locks(lines)
+      advisory_locks.each do |lock|
+        lines << ""
+        lines << "Leaked advisory lock:"
+        lines << "  name: #{lock.human_name}" if lock.human_name
+        lines << "  key: (classid=#{lock.class_id}, objid=#{lock.object_key}, mode=#{lock.mode})"
+        location = latest_suspicion(kind: :advisory_lock)&.call_site
+        lines << "  acquired at: #{location}" if location
+      end
+    end
+
+    def append_setting_changes(lines)
+      setting_changes.each do |change|
+        expected = change.comparison == :baseline ? change.baseline : change.reset_value
+        lines << ""
+        lines << "Changed session setting:"
+        lines << "  #{change.name}"
+        lines << "  expected: #{expected.inspect}"
+        lines << "  actual:   #{change.current.inspect}"
+        location = latest_suspicion(setting: change.name)&.call_site
+        lines << "  last SET at: #{location}" if location
+      end
+    end
+
+    def append_user_level_locks(lines)
+      user_level_locks.each do |lock|
+        lines << ""
+        lines << "Leaked MySQL user-level lock:"
+        lines << "  name: #{lock.name}"
+        lines << "  confidence: #{lock.confidence}"
+        lines << "  acquisition count: #{lock.acquisition_count}" if lock.acquisition_count
+        lines << "  status: #{lock.status}" if lock.status
+        location = latest_suspicion(kind: :user_level_lock, lock_name: lock.name)&.call_site
+        lines << "  acquired at: #{location}" if location
+      end
+    end
+
+    def append_suspicions(lines)
+      return if suspicions.empty?
+
+      lines << ""
+      lines << "Suspicious statements:"
+      suspicions.each do |suspicion|
+        location = suspicion.call_site ? " (#{suspicion.call_site})" : ""
+        lines << "  #{suspicion.sql.to_s.strip}#{location}"
+      end
+    end
+
+    def append_remediation(lines)
+      lines << ""
+      lines << "Reset the state before releasing the connection"
+      lines << "(for example, RESET ROLE / RESET search_path / pg_advisory_unlock_all() /"
+      lines << "RELEASE_ALL_LOCKS()),"
+      lines << "or ensure cleanup runs in an ensure block."
+    end
+
+    def boundary_message
+      if inspection_point == :checkin
+        return "Connection was returned to the pool with modified session state."
+      end
+
+      "Connection was handed out with session state left over\nfrom a previous owner."
+    end
+
+    def latest_suspicion(kind: nil, setting: nil, lock_name: nil)
+      suspicions.reverse.find do |suspicion|
+        (!kind || suspicion.kind == kind) &&
+          (!setting || suspicion.setting == setting) &&
+          (!lock_name || suspicion.lock_name == lock_name)
+      end
+    end
+  end
+end

data/lib/poollint/sql_watcher.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module PoolLint
+  class SqlWatcher
+    Detection = Struct.new(
+      :kind,
+      :setting,
+      :lock_operation,
+      :lock_name,
+      keyword_init: true
+    )
+
+    ADVISORY_PATTERN = /
+      \bpg_(?:try_)?advisory_
+      (?:lock(?:_shared)?|unlock(?:_shared|_all)?)\s*\(
+    /ix
+    LEADING_COMMENTS = %r{\A(?:\s+|/\*.*?\*/|--[^\n]*(?:\n|\z))*}m
+    MYSQL_LOCK_OPERATIONS = {
+      "GET_LOCK" => :acquire,
+      "RELEASE_LOCK" => :release,
+      "RELEASE_ALL_LOCKS" => :release_all
+    }.freeze
+    MYSQL_LOCK_PATTERN = /\b(GET_LOCK|RELEASE_LOCK|RELEASE_ALL_LOCKS)\s*\(/i
+    SETTING_PATTERN = /\A[a-z_][a-z0-9_.-]*/i
+    SPECIAL_SETTINGS = {
+      "NAMES" => "client_encoding",
+      "ROLE" => "role",
+      "SCHEMA" => "search_path",
+      "SESSION AUTHORIZATION" => "session_authorization",
+      "TIME ZONE" => "timezone",
+      "XML OPTION" => "xmloption"
+    }.freeze
+
+    class << self
+      def install!
+        return if @subscriber
+
+        @subscriber = ActiveSupport::Notifications.subscribe("sql.active_record") do |*args|
+          process(args.last)
+        end
+      end
+
+      def process(payload)
+        return if ExecutionState.inspecting?
+        return if payload[:name] == "SCHEMA"
+
+        connection = payload[:connection]
+        detection = detect(payload[:sql])
+        return unless connection && detection
+
+        state_for(connection).mark_dirty(
+          kind: detection.kind,
+          setting: detection.setting,
+          sql: payload[:sql],
+          call_site: application_call_site,
+          monitor_setting: PoolLint.configuration.track_custom_gucs,
+          lock_operation: detection.lock_operation,
+          lock_name: detection.lock_name
+        )
+      end
+
+      def detect(sql)
+        statement = sql.to_s.sub(LEADING_COMMENTS, "").strip
+        return if statement.empty?
+        return Detection.new(kind: :advisory_lock) if statement.match?(ADVISORY_PATTERN)
+
+        detect_user_level_lock(statement) || detect_set(statement) || detect_reset(statement)
+      end
+
+      private
+
+      def application_call_site
+        location = caller_locations.find do |candidate|
+          path = candidate.absolute_path || candidate.path
+          path &&
+            !path.include?("/lib/poollint/") &&
+            !path.include?("/gems/") &&
+            !path.include?("/active_support/")
+        end
+        return unless location
+
+        "#{location.path}:#{location.lineno}"
+      end
+
+      def detect_reset(statement)
+        match = statement.match(/\ARESET\s+(.+?)(?:\s*;)?\z/im)
+        return unless match
+
+        key = normalize_setting(match[1])
+        Detection.new(kind: :reset, setting: key == "all" ? nil : key)
+      end
+
+      def detect_user_level_lock(statement)
+        match = statement.match(MYSQL_LOCK_PATTERN)
+        return unless match
+
+        function = match[1].upcase
+        Detection.new(
+          kind: :user_level_lock,
+          lock_operation: MYSQL_LOCK_OPERATIONS.fetch(function),
+          lock_name: mysql_lock_name(statement, function)
+        )
+      end
+
+      def state_for(connection)
+        ConnectionState.fetch(
+          connection,
+          suspicion_limit: PoolLint.configuration.suspicion_limit
+        )
+      end
+
+      def detect_set(statement)
+        return if statement.match?(/\ASET\s+(?:LOCAL|TRANSACTION)\b/i)
+
+        session_authorization = statement.match?(/\ASET\s+SESSION\s+AUTHORIZATION\b/i)
+        return Detection.new(kind: :set, setting: "session_authorization") if session_authorization
+
+        mysql_transaction = detect_mysql_session_transaction(statement)
+        return mysql_transaction if mysql_transaction
+
+        match = statement.match(/\ASET\s+(?:SESSION\s+)?(.+)\z/im)
+        return unless match
+
+        body = match[1].strip
+        return if body.match?(/\A(?:CONSTRAINTS|TRANSACTION)\b/i)
+
+        key = normalize_setting(body)
+        Detection.new(kind: :set, setting: key)
+      end
+
+      def normalize_setting(body)
+        normalized = body.to_s.strip.sub(/;\z/, "")
+        normalized = normalized.sub(/\A@@(?:SESSION\.)?/i, "")
+        normalized = normalized.upcase
+        special = SPECIAL_SETTINGS.find { |name, _| normalized.start_with?(name) }
+        return special.last if special
+
+        normalized.downcase.match(SETTING_PATTERN)&.to_s
+      end
+
+      def mysql_lock_name(statement, function)
+        return if function == "RELEASE_ALL_LOCKS"
+
+        pattern = /\b#{function}\s*\(\s*(?:'((?:\\.|''|[^'])*)'|"((?:\\.|""|[^"])*)")/im
+        match = statement.match(pattern)
+        return unless match
+
+        name = match[1]&.gsub("''", "'") || match[2]&.gsub('""', '"')
+        name&.gsub(/\\(.)/, '\1')
+      end
+
+      def detect_mysql_session_transaction(statement)
+        match = statement.match(/\ASET\s+SESSION\s+TRANSACTION\s+(.+)\z/im)
+        return unless match
+
+        setting = if match[1].match?(/\AISOLATION\s+LEVEL\b/i)
+                    "transaction_isolation"
+                  elsif match[1].match?(/\AREAD\s+(?:ONLY|WRITE)\b/i)
+                    "transaction_read_only"
+                  end
+        Detection.new(kind: :set, setting: setting) if setting
+      end
+    end
+  end
+end

data/lib/poollint/suspicion_log.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module PoolLint
+  Suspicion = Struct.new(
+    :kind,
+    :setting,
+    :sql,
+    :call_site,
+    :lock_operation,
+    :lock_name,
+    keyword_init: true
+  )
+
+  class SuspicionLog
+    SQL_LIMIT = 200
+
+    def initialize(limit:)
+      @limit = limit
+      @entries = []
+    end
+
+    def add(suspicion)
+      @entries.shift if @entries.length >= @limit
+      @entries << normalized(suspicion)
+    end
+
+    def clear
+      @entries.clear
+    end
+
+    def entries
+      @entries.dup
+    end
+
+    private
+
+    def normalized(suspicion)
+      suspicion.dup.tap do |entry|
+        entry.sql = entry.sql.to_s.slice(0, SQL_LIMIT)
+      end
+    end
+  end
+end

data/lib/poollint/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PoolLint
+  VERSION = "0.1.0"
+end

data/lib/poollint.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "poollint/version"
+require_relative "poollint/errors"
+require_relative "poollint/execution_state"
+require_relative "poollint/configuration"
+require_relative "poollint/suspicion_log"
+require_relative "poollint/connection_state"
+require_relative "poollint/sql_watcher"
+require_relative "poollint/report"
+require_relative "poollint/allowed_settings"
+require_relative "poollint/kannuki_lock_resolver"
+require_relative "poollint/inspectors/postgresql_capture"
+require_relative "poollint/inspectors/postgresql"
+require_relative "poollint/inspectors/mysql"
+require_relative "poollint/inspectors"
+require_relative "poollint/notifier"
+require_relative "poollint/inspection_runner"
+require_relative "poollint/hooks/checkout_hook"
+require_relative "poollint/hooks/checkin_hook"
+require_relative "poollint/hooks/lifecycle"
+require_relative "poollint/hooks"
+
+module PoolLint
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield configuration
+      configuration.validate!
+    end
+
+    def connection_state(connection)
+      ConnectionState.fetch(
+        connection,
+        suspicion_limit: configuration.suspicion_limit
+      )
+    end
+
+    def install!
+      require "active_record"
+
+      SqlWatcher.install!
+      Hooks.install!
+      warn_about_checkin_in_production
+    end
+
+    def log_warning(message)
+      logger = configuration.logger
+      logger ||= ActiveRecord::Base.logger if defined?(ActiveRecord::Base)
+      formatted = "[PoolLint] #{message}"
+      return warn_with_logger(logger, formatted) if logger
+
+      Kernel.warn(formatted)
+    rescue StandardError
+      nil
+    end
+
+    def reset_configuration!(environment: nil)
+      @configuration = Configuration.new(environment: environment)
+    end
+
+    def suppress(&)
+      ExecutionState.suppress(&)
+    end
+
+    private
+
+    def warn_with_logger(logger, message)
+      logger.warn(message)
+    rescue StandardError => e
+      Kernel.warn("#{message} (logger failed: #{e.class}: #{e.message})")
+    end
+
+    def warn_about_checkin_in_production
+      return unless configuration.inspection_point == :checkin
+      return if configuration.test_environment?
+
+      log_warning(
+        ":checkin inspection runs while the Active Record pool mutex is held; " \
+        "use :checkout in production"
+      )
+    end
+  end
+end
+
+require_relative "poollint/railtie" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: poollint
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: |
+  PoolLint checks Active Record connections at pool boundaries and reports
+  PostgreSQL or MySQL settings and locks that leaked from a previous borrower.
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- docs/pool_locking.md
+- docs/releasing.md
+- lib/poollint.rb
+- lib/poollint/allowed_settings.rb
+- lib/poollint/configuration.rb
+- lib/poollint/connection_state.rb
+- lib/poollint/errors.rb
+- lib/poollint/execution_state.rb
+- lib/poollint/hooks.rb
+- lib/poollint/hooks/checkin_hook.rb
+- lib/poollint/hooks/checkout_hook.rb
+- lib/poollint/hooks/lifecycle.rb
+- lib/poollint/inspection_runner.rb
+- lib/poollint/inspectors.rb
+- lib/poollint/inspectors/mysql.rb
+- lib/poollint/inspectors/postgresql.rb
+- lib/poollint/inspectors/postgresql_capture.rb
+- lib/poollint/kannuki_lock_resolver.rb
+- lib/poollint/notifier.rb
+- lib/poollint/railtie.rb
+- lib/poollint/report.rb
+- lib/poollint/sql_watcher.rb
+- lib/poollint/suspicion_log.rb
+- lib/poollint/version.rb
+homepage: https://github.com/ydah/poollint
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/ydah/poollint
+  source_code_uri: https://github.com/ydah/poollint
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Detect database session state leaked through Active Record connection pools
+test_files: []