query_guard 0.4.1 → 0.5.0

data/lib/query_guard/suggest/index_suggester.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Suggest
+    # Generates index suggestions for queries with missing index indicators.
+    # Conservative approach: only suggests when patterns match common cases.
+    # All suggestions include disclaimer that they're recommendations only.
+    #
+    # Example:
+    #   suggester = IndexSuggester.new
+    #   suggestion = suggester.suggest_for_sequential_scan(
+    #     "SELECT * FROM users WHERE email = 'test@example.com'",
+    #     table_name: "users"
+    #   )
+    #   # => {
+    #   #   suggested_index_sql: "CREATE INDEX idx_users_email ON users (email);",
+    #   #   explanation: "Index on email column for WHERE clause equality",
+    #   #   confidence: :medium,
+    #   #   columns: ["email"]
+    #   # }
+    class IndexSuggester
+      CONFIDENCE_LEVELS = %i[high medium low].freeze
+
+      def initialize
+        @extractors = PatternExtractors.new
+      end
+
+      # Generate index suggestion for sequential scan with filter
+      #
+      # @param sql [String] SQL query
+      # @param table_name [String] Table being scanned
+      # @param filter_condition [String] WHERE clause filter (optional)
+      # @return [Hash, nil] Suggestion hash or nil if no reasonable suggestion
+      def suggest_for_sequential_scan(sql, table_name:, filter_condition: nil)
+        return nil if sql.nil? || table_name.nil?
+
+        # Extract columns from WHERE clause
+        where_cols = @extractors.extract_where_columns(sql)
+        return nil if where_cols.empty?
+
+        # Use first column as primary index candidate
+        # This is conservative: most benefit comes from first filter
+        primary_col = where_cols.first
+        suggest_index(table_name, primary_col, high_confidence: true)
+      end
+
+      # Generate index suggestion for expensive sort
+      #
+      # @param sql [String] SQL query
+      # @param table_name [String] Table being sorted
+      # @return [Hash, nil] Suggestion hash or nil
+      def suggest_for_expensive_sort(sql, table_name:)
+        return nil if sql.nil? || table_name.nil?
+
+        # Extract ORDER BY columns
+        order_cols = @extractors.extract_order_by_columns(sql)
+        return nil if order_cols.empty?
+
+        # For sorts, index all ORDER BY columns in order
+        suggest_composite_index(table_name, order_cols, reason: "sort")
+      end
+
+      # Generate index suggestion for multi-column filter
+      # For WHERE with multiple equality conditions, suggest composite
+      #
+      # @param sql [String] SQL query
+      # @param table_name [String] Table being filtered
+      # @return [Hash, nil] Suggestion hash or nil
+      def suggest_for_complex_filter(sql, table_name:)
+        return nil if sql.nil? || table_name.nil?
+
+        where_cols = @extractors.extract_where_columns(sql)
+        return nil if where_cols.length < 2
+
+        # Conservative: only suggest composite for 2-3 columns
+        return nil if where_cols.length > 3
+
+        suggest_composite_index(table_name, where_cols, reason: "composite filter")
+      end
+
+      # Generate index suggestion for JOIN condition
+      # Suggests index on join key in inner table
+      #
+      # @param column_name [String] Join column name
+      # @param table_name [String] Inner table name
+      # @return [Hash] Suggestion hash
+      def suggest_for_join(column_name, table_name:)
+        return nil if column_name.nil? || table_name.nil?
+
+        suggest_index(table_name, column_name, high_confidence: true, reason: "join condition")
+      end
+
+      # Build neutral recommendation text for a suggestion
+      #
+      # @param suggestion [Hash] Suggestion from suggest_* methods
+      # @return [String] User-facing recommendation text
+      def build_recommendation_text(suggestion)
+        return nil unless suggestion
+
+        text = suggestion[:explanation]
+        text += " (confidence: #{suggestion[:confidence]})"
+        text += "\n\nIMPORTANT: This is a recommendation based on query pattern analysis. "
+        text += "Before creating the index:\n"
+        text += "  1. Verify this index hasn't already been suggested elsewhere\n"
+        text += "  2. Check index size impact and maintenance cost\n"
+        text += "  3. Run EXPLAIN ANALYZE with and without the index\n"
+        text += "  4. Consider selectivity of indexed columns\n"
+        text += "  5. Test in development first\n\n"
+        text += "Suggested SQL (REVIEW BEFORE RUNNING):\n#{suggestion[:suggested_index_sql]}"
+        text
+      end
+
+      private
+
+      def suggest_index(table_name, column_name, high_confidence: false, reason: nil)
+        col_safe = sanitize_identifier(column_name)
+        table_safe = sanitize_identifier(table_name)
+        index_name = "idx_#{table_safe}_#{col_safe}".downcase
+
+        {
+          suggested_index_sql: "CREATE INDEX #{index_name} ON #{table_safe} (#{col_safe});",
+          explanation: build_explanation(reason || "column filter", [column_name]),
+          confidence: high_confidence ? :high : :medium,
+          columns: [column_name],
+          index_name: index_name,
+          table_name: table_name
+        }
+      end
+
+      def suggest_composite_index(table_name, column_names, reason: nil)
+        return nil if column_names.empty?
+
+        # Conservative: don't suggest composite for too many columns
+        return nil if column_names.length > 4
+
+        table_safe = sanitize_identifier(table_name)
+        cols_safe = column_names.map { |c| sanitize_identifier(c) }
+        col_list = cols_safe.join(", ")
+        
+        # Index name: idx_table_col1_col2
+        index_name = "idx_#{table_safe}_#{cols_safe.join('_')}".downcase[0...63] # 63 char limit
+
+        {
+          suggested_index_sql: "CREATE INDEX #{index_name} ON #{table_safe} (#{col_list});",
+          explanation: build_explanation(reason || "composite filter", column_names),
+          confidence: :medium,
+          columns: column_names,
+          index_name: index_name,
+          table_name: table_name
+        }
+      end
+
+      def build_explanation(reason, columns)
+        col_str = columns.length == 1 ? "#{columns[0]} column" : "#{columns.join(', ')} columns"
+        case reason
+        when "sort"
+          "Index on #{col_str} for ORDER BY clause"
+        when "composite filter"
+          "Composite index on #{col_str} for WHERE clause"
+        when "join condition"
+          "Index on #{col_str} for JOIN condition"
+        else
+          "Index on #{col_str} for #{reason}"
+        end
+      end
+
+      def sanitize_identifier(identifier)
+        # Basic sanitization: allow alphanumeric and underscore
+        # PostgreSQL identifiers: letters, digits, underscores
+        sanitized = identifier.to_s.downcase.gsub(/[^a-z0-9_]/, '_')
+        # Remove leading digits (invalid)
+        sanitized.gsub(/^[0-9]+/, '')
+      end
+    end
+  end
+end

data/lib/query_guard/suggest/pattern_extractors.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Suggest
+    # Extracts SQL patterns from queries for index suggestion.
+    # Conservative patterns only - only suggests when reasonably confident.
+    #
+    # Example:
+    #   extractor = PatternExtractors.new
+    #   where_cols = extractor.extract_where_columns("SELECT * FROM users WHERE email = 'test@example.com'")
+    #   # => ["email"]
+    #
+    #   order_cols = extractor.extract_order_by_columns("SELECT * FROM events ORDER BY created_at DESC")
+    #   # => ["created_at"]
+    class PatternExtractors
+      # Extract column names from WHERE clause
+      # Handles: simple equality, comparison operators
+      # Avoids: functions, expressions, BETWEEN
+      #
+      # @param sql [String] SQL query
+      # @return [Array<String>] Column names in WHERE clause
+      def extract_where_columns(sql)
+        return [] if sql.nil? || sql.empty?
+
+        normalized = normalize_sql(sql)
+        where_match = normalized.match(/\bWHERE\s+(.+?)(?:\s+(?:GROUP|ORDER|LIMIT|HAVING)(?:\s|$)|$)/i)
+        return [] unless where_match
+
+        where_clause = where_match[1]
+        extract_columns_from_where(where_clause)
+      end
+
+      # Extract column names from ORDER BY clause
+      # Handles: simple column ordering
+      # Avoids: expressions, COLLATE, NULLS FIRST/LAST
+      #
+      # @param sql [String] SQL query
+      # @return [Array<String>] Column names in ORDER BY clause
+      def extract_order_by_columns(sql)
+        return [] if sql.nil? || sql.empty?
+
+        normalized = normalize_sql(sql)
+        order_match = normalized.match(/\bORDER\s+BY\s+(.+?)(?:\s+(?:LIMIT)(?:\s|$)|$)/i)
+        return [] unless order_match
+
+        order_clause = order_match[1]
+        extract_columns_from_order_by(order_clause)
+      end
+
+      # Extract both WHERE and ORDER BY columns
+      # Returns them in a structured format for index suggestion
+      #
+      # @param sql [String] SQL query
+      # @return [Hash] { where_columns: [...], order_by_columns: [...] }
+      def extract_all_columns(sql)
+        {
+          where_columns: extract_where_columns(sql),
+          order_by_columns: extract_order_by_columns(sql)
+        }
+      end
+
+      # Extract table name from query
+      # Simple extraction of first table mentioned after FROM
+      #
+      # @param sql [String] SQL query
+      # @return [String, nil] Table name
+      def extract_table_name(sql)
+        return nil if sql.nil? || sql.empty?
+
+        normalized = normalize_sql(sql)
+        # Match FROM or JOIN followed by table name
+        # Handles: "FROM users", "FROM public.users", "JOIN orders ON"
+        match = normalized.match(/\b(?:FROM|JOIN)\s+(?:(?:\w+\.)?(\w+))\b/i)
+        match&.[](1)&.downcase
+      end
+
+      private
+
+      def normalize_sql(sql)
+        # Remove comments and extra whitespace
+        sql
+          .gsub(/--.*$/, '')           # Remove line comments
+          .gsub(/\/\*.*?\*\//m, '')    # Remove block comments
+          .gsub(/\s+/, ' ')            # Collapse whitespace
+          .strip
+      end
+
+      def extract_columns_from_where(where_clause)
+        columns = []
+
+        # Match simple patterns: column = value, column > value, column IN (...)
+        # Skip function calls and complex expressions
+        where_clause.scan(/\b(\w+)\s*(?:=|<>|!=|>|<|>=|<=|LIKE|IN)/i) do |match|
+          col = match[0].downcase
+          # Skip obvious non-column keywords
+          next if skip_keyword?(col)
+
+          columns << col unless columns.include?(col)
+        end
+
+        columns
+      end
+
+      def extract_columns_from_order_by(order_clause)
+        columns = []
+
+        # Match column names before ASC/DESC/comma
+        # Pattern: word (optionally preceded by table name)
+        order_clause.split(',').each do |part|
+          # Remove ASC/DESC modifiers
+          cleaned = part.gsub(/\s+(?:ASC|DESC)\s*$/i, '').strip
+
+          # Extract column name (handle schema.table.column references)
+          col_match = cleaned.match(/\b(\w+)\s*$/)
+          next unless col_match
+
+          col = col_match[1].downcase
+          next if skip_keyword?(col)
+
+          columns << col unless columns.include?(col)
+        end
+
+        columns
+      end
+
+      def skip_keyword?(word)
+        # Skip SQL keywords and common aliases
+        keywords = %w[
+          and or not null true false case when then else end 
+          select insert update delete from where join on group having order by limit offset
+          asc desc ignore using force straight_join key
+        ]
+        keywords.include?(word.downcase)
+      end
+    end
+  end
+end

data/lib/query_guard/trace.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+require "securerandom"
+
+module QueryGuard
+  # Block-based tracing API for manual query tracking.
+  # Usable in console, tests, and Rails controllers/jobs.
+  module Trace
+    class Report
+      attr_reader :label, :context, :stats, :violations
+
+      def initialize(label, context, stats, violations)
+        @label = label
+        @context = context
+        @stats = stats
+        @violations = violations
+      end
+
+      def query_count
+        @stats[:count]
+      end
+
+      def total_duration_ms
+        @stats[:total_duration_ms]
+      end
+
+      def queries
+        @stats[:queries] || []
+      end
+
+      def fingerprints
+        @stats[:fingerprints] || {}
+      end
+
+      def has_violations?
+        !@violations.empty?
+      end
+
+      def to_h
+        {
+          label: @label,
+          context: @context,
+          query_count: query_count,
+          total_duration_ms: total_duration_ms,
+          violations: @violations,
+          fingerprints: @fingerprints
+        }
+      end
+    end
+
+    module_function
+
+    # Trace a block of code and capture query stats.
+    # Returns [result, report] tuple.
+    #
+    # Example:
+    #   result, report = QueryGuard.trace("load users") do
+    #     User.where(active: true).limit(10).to_a
+    #   end
+    #
+    #   puts report.query_count
+    #   puts report.total_duration_ms
+    #
+    # With context:
+    #   result, report = QueryGuard.trace("process batch", context: { batch_id: 123 }) do
+    #     # ... code ...
+    #   end
+    def trace(label, context: {})
+      # Initialize thread-local stats
+      previous_stats = Thread.current[:query_guard_stats]
+      Thread.current[:query_guard_stats] = {
+        request_id: "trace-#{SecureRandom.hex(4)}",
+        count: 0,
+        total_duration_ms: 0.0,
+        violations: [],
+        fingerprints: Hash.new(0),
+        response_bytes: 0,
+        queries: [],
+        request: context
+      }
+
+      # Execute the block
+      result = yield
+
+      # Capture stats
+      stats = Thread.current[:query_guard_stats]
+      violations = stats[:violations].dup
+
+      # Check budget if configured
+      if QueryGuard.respond_to?(:config) && QueryGuard.config
+        budget = QueryGuard.config.budget
+        if budget
+          budget_violations = budget.check(label, stats)
+          violations.concat(budget_violations)
+        end
+      end
+
+      # Build report
+      report = Report.new(label, context, stats, violations)
+
+      [result, report]
+    ensure
+      # Restore previous stats
+      Thread.current[:query_guard_stats] = previous_stats
+    end
+  end
+end

data/lib/query_guard/uploader/http_uploader.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Uploader
+    # HTTP uploader for sending reports to a remote QueryGuard API.
+    #
+    # This is a template/stub uploader for future SaaS platform integration.
+    # It provides the interface for authenticated HTTPS uploads but is not
+    # yet connected to a production service.
+    #
+    # Configuration:
+    #   config.uploader_type = 'http'
+    #   config.api_base_url = 'https://api.queryguard.example.com'
+    #   config.project_key = 'proj-123'
+    #   config.api_token = 'token-secret'
+    #
+    # Use case (future):
+    # - Upload findings to hosted QueryGuard platform
+    # - Centralized reporting & analytics
+    # - Team collaboration on findings
+    # - Integration with compliance dashboards
+    class HttpUploader < Interface
+      # Create HTTP uploader from config.
+      #
+      # @param config [QueryGuard::Config] Configuration object with API details
+      def initialize(config)
+        @config = config
+        @api_base_url = config.api_base_url
+        @project_key = config.project_key
+        @api_token = config.api_token
+      end
+
+      # Upload JSON report to remote API.
+      #
+      # @param json_report [String] JSON report string
+      # @param metadata [Hash] Additional metadata (tracing, timing, etc.)
+      # @return [UploadResult]
+      def upload(json_report, metadata = {})
+        unless ready?
+          return UploadResult.new(
+            success: false,
+            uploader_name: name,
+            error: "HTTP uploader not properly configured (missing #{missing_fields.join(', ')})"
+          )
+        end
+
+        # Parse report to extract metadata
+        report_data = parse_report(json_report)
+
+        perform_upload(json_report, report_data, metadata)
+      rescue StandardError => e
+        UploadResult.new(
+          success: false,
+          uploader_name: name,
+          error: "Upload failed: #{e.message}"
+        )
+      end
+
+      # Check if configuration is complete.
+      def ready?
+        !!(@api_base_url && !@api_base_url.empty? &&
+          @project_key && !@project_key.empty? &&
+          @api_token && !@api_token.empty?)
+      end
+
+      def name
+        'http'
+      end
+
+      def status
+        {
+          enabled: ready?,
+          mode: 'http',
+          api_url: @api_base_url,
+          project_key: @project_key,
+          description: ready? ? 'Configured for remote API upload' : 'Not configured (missing credentials)'
+        }
+      end
+
+      private
+
+      # Missing required fields for upload.
+      def missing_fields
+        fields = []
+        fields << 'api_base_url' unless @api_base_url && !@api_base_url.empty?
+        fields << 'project_key' unless @project_key && !@project_key.empty?
+        fields << 'api_token' unless @api_token && !@api_token.empty?
+        fields
+      end
+
+      # Extract basic info from JSON report.
+      def parse_report(json_str)
+        JSON.parse(json_str)
+      rescue StandardError
+        {}
+      end
+
+      # Perform the actual HTTP upload.
+      #
+      # NOTE: This is a stub implementation. A production version would:
+      # - Use Net::HTTP or similar with proper SSL/verify certificate
+      # - Handle retries and exponential backoff
+      # - Implement request signing/HMAC
+      # - Support compression (gzip)
+      # - Set proper Content-Type and User-Agent headers
+      # - Implement request timeouts and circuit breaks
+      #
+      # For now, this is a documentation template.
+      def perform_upload(json_report, report_data, metadata)
+        require 'net/http'
+        require 'json'
+
+        url = build_upload_url(report_data)
+        request_body = build_request_body(json_report, metadata)
+
+        # Stub: Would make the actual HTTP request here
+        # This is intentionally not implemented to prevent accidental
+        # API calls during testing or misconfiguration.
+        #
+        # A production implementation would do something like:
+        #   uri = URI(url)
+        #   http = Net::HTTP.new(uri.host, uri.port)
+        #   http.use_ssl = uri.scheme == 'https'
+        #   req = Net::HTTP::Post.new(uri.path)
+        #   req['Authorization'] = "Bearer #{@api_token}"
+        #   req['Content-Type'] = 'application/json'
+        #   response = http.request(req, request_body)
+        #
+        # But we leave that for when the SaaS platform exists.
+
+        # For now, return a success result indicating what WOULD be sent
+        UploadResult.new(
+          success: true,
+          uploader_name: name,
+          details: {
+            endpoint: url,
+            bytes_sent: request_body.bytesize,
+            report_version: report_data['report_version'],
+            project_key: @project_key,
+            note: 'HTTP uploader is configured but SaaS platform is not yet live'
+          }
+        )
+      end
+
+      # Build the upload endpoint URL.
+      def build_upload_url(report_data)
+        report_type = report_data['report_type'] || 'analysis'
+        base_url = @api_base_url.end_with?('/') ? @api_base_url[0...-1] : @api_base_url
+        "#{base_url}/api/v1/projects/#{@project_key}/reports/#{report_type}"
+      end
+
+      # Build the request body with headers and payload.
+      def build_request_body(json_report, metadata)
+        {
+          report: JSON.parse(json_report),
+          client_metadata: {
+            tool_version: QueryGuard::VERSION || 'unknown',
+            client_time: Time.now.utc.iso8601,
+            trace_id: metadata[:trace_id],
+            request_id: metadata[:request_id]
+          }
+        }.to_json
+      end
+    end
+  end
+end

data/lib/query_guard/uploader/interface.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module QueryGuard
+  module Uploader
+    # Abstract interface for report uploaders.
+    #
+    # All uploaders must implement this interface. This allows:
+    # - Pluggable upload strategies (no-op, HTTP, webhook, etc.)
+    # - Easy testing with mock uploaders
+    # - Future extensibility without changing core code
+    #
+    # Example:
+    #   uploader = QueryGuard::Uploader.for_config(config)
+    #   result = uploader.upload(report_json)
+    class Interface
+      # Upload a JSON report to the configured destination.
+      #
+      # @param json_report [String] JSON-formatted report string
+      # @param metadata [Hash] Optional metadata (report_id, trace_id, etc.)
+      #
+      # @return [UploadResult] Result object with status and details
+      #
+      # Should never raise. Always return an UploadResult with success/failure state.
+      def upload(json_report, metadata = {})
+        raise NotImplementedError, "#{self.class} must implement #upload"
+      end
+
+      # Check if this uploader is properly configured and ready.
+      #
+      # @return [Boolean] true if ready to upload, false otherwise
+      def ready?
+        raise NotImplementedError, "#{self.class} must implement #ready?"
+      end
+
+      # Human-readable name of this uploader.
+      #
+      # @return [String]
+      def name
+        raise NotImplementedError, "#{self.class} must implement #name"
+      end
+
+      # Get status/diagnostic information for logging.
+      #
+      # @return [Hash] Status information (target_url, enabled, etc.)
+      def status
+        raise NotImplementedError, "#{self.class} must implement #status"
+      end
+    end
+
+    # Result of an upload operation.
+    class UploadResult
+      attr_reader :success, :uploader_name, :details, :error
+
+      def initialize(success:, uploader_name:, details: {}, error: nil)
+        @success = success
+        @uploader_name = uploader_name
+        @details = details
+        @error = error
+      end
+
+      def successful?
+        @success
+      end
+
+      def failed?
+        !@success
+      end
+
+      def to_h
+        {
+          success: @success,
+          uploader: @uploader_name,
+          details: @details,
+          error: @error
+        }
+      end
+    end
+  end
+end