rails-informant 0.0.1

data/lib/rails_informant/breadcrumb_buffer.rb

@@ -0,0 +1,30 @@
+module RailsInformant
+  class BreadcrumbBuffer
+    CAPACITY = 50
+
+    def self.current
+      RailsInformant::Current.breadcrumbs ||= new
+    end
+
+    def initialize
+      @crumbs = []
+    end
+
+    def record(category:, message:, metadata: {}, duration: nil)
+      @crumbs << {
+        category:,
+        message:,
+        metadata:,
+        duration:,
+        timestamp: Time.current.iso8601(3)
+      }
+      @crumbs.shift if @crumbs.size > CAPACITY
+    end
+
+    def flush
+      result = @crumbs
+      @crumbs = []
+      result
+    end
+  end
+end

data/lib/rails_informant/breadcrumb_subscriber.rb

@@ -0,0 +1,51 @@
+module RailsInformant
+  class BreadcrumbSubscriber
+    NEEDS_FILTERING = %w[
+      process_action.action_controller
+      redirect_to.action_controller
+      start_processing.action_controller
+    ].to_set.freeze
+
+    SUBSCRIPTIONS = {
+      "cache_fetch_hit.active_support" => %i[key],
+      "cache_read.active_support" => %i[key hit],
+      "cache_write.active_support" => %i[key],
+      "deliver.action_mailer" => %i[mailer],
+      "halted_callback.action_controller" => %i[filter],
+      "instantiation.active_record" => %i[record_count class_name],
+      "perform.active_job" => %i[job],
+      "perform_action.action_cable" => %i[channel_class action],
+      "perform_start.active_job" => %i[job],
+      "process_action.action_controller" => %i[controller action method path status],
+      "redirect_to.action_controller" => %i[status location],
+      "render_collection.action_view" => %i[identifier count],
+      "render_partial.action_view" => %i[identifier],
+      "render_template.action_view" => %i[identifier],
+      "sql.active_record" => %i[name],
+      "start_processing.action_controller" => %i[action controller format method path]
+    }.freeze
+
+    def self.subscribe!
+      SUBSCRIPTIONS.each do |event_name, allowed_keys|
+        message = event_name.split(".").first
+
+        ActiveSupport::Notifications.subscribe(event_name) do |event|
+          next unless RailsInformant.initialized?
+          next if event_name == "sql.active_record" && (event.payload[:cached] || event.payload[:name] == "SCHEMA")
+
+          filtered = event.payload.slice(*allowed_keys)
+          filtered = ContextFilter.filter(filtered) if NEEDS_FILTERING.include?(event_name)
+          if event_name == "redirect_to.action_controller" && filtered[:location]
+            filtered[:location] = ContextBuilder.filtered_url filtered[:location]
+          end
+          BreadcrumbBuffer.current.record(
+            category: event.name,
+            message:,
+            metadata: filtered,
+            duration: event.duration.round(1)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/rails_informant/configuration.rb

@@ -0,0 +1,51 @@
+module RailsInformant
+  class Configuration
+    attr_accessor :api_token,
+                  :capture_errors,
+                  :capture_user_email,
+                  :devin_api_key,
+                  :devin_playbook_id,
+                  :ignored_exceptions,
+                  :retention_days,
+                  :slack_webhook_url,
+                  :webhook_url
+
+    def initialize
+      @api_token = ENV["INFORMANT_API_TOKEN"]
+      @capture_errors = ENV.fetch("INFORMANT_CAPTURE_ERRORS", "true") != "false"
+      @capture_user_email = false
+      @custom_notifiers = []
+      @devin_api_key = ENV["INFORMANT_DEVIN_API_KEY"]
+      @devin_playbook_id = ENV["INFORMANT_DEVIN_PLAYBOOK_ID"]
+      @ignored_exceptions = ENV["INFORMANT_IGNORED_EXCEPTIONS"]&.split(",")&.map(&:strip) || []
+      @retention_days = ENV["INFORMANT_RETENTION_DAYS"]&.to_i
+      @slack_webhook_url = ENV["INFORMANT_SLACK_WEBHOOK_URL"]
+      @webhook_url = ENV["INFORMANT_WEBHOOK_URL"]
+    end
+
+    # Returns all notifiers: built-in (auto-registered from config) + custom.
+    def notifiers
+      @_notifiers ||= built_in_notifiers + @custom_notifiers
+    end
+
+    # Register a custom notifier. Must respond to #notify and #should_notify?.
+    def add_notifier(notifier)
+      @custom_notifiers << notifier
+      @_notifiers = nil
+    end
+
+    def reset_notifiers!
+      @_notifiers = nil
+    end
+
+    private
+
+    def built_in_notifiers
+      [
+        (Notifiers::Devin.new if devin_api_key.present? && devin_playbook_id.present?),
+        (Notifiers::Slack.new if slack_webhook_url.present?),
+        (Notifiers::Webhook.new if webhook_url.present?)
+      ].compact
+    end
+  end
+end

data/lib/rails_informant/context_builder.rb

@@ -0,0 +1,142 @@
+module RailsInformant
+  class ContextBuilder
+    MAX_CAUSE_DEPTH = 5
+    SKIP_HEADERS = Set.new(%w[
+      HTTP_AUTHORIZATION
+      HTTP_COOKIE
+      HTTP_PROXY_AUTHORIZATION
+      HTTP_X_API_KEY
+      HTTP_X_AUTH_TOKEN
+      HTTP_X_CSRF_TOKEN
+    ]).freeze
+
+    class << self
+      def build_exception_chain(error)
+        chain = []
+        current = error.cause
+        depth = 0
+
+        while current && depth < MAX_CAUSE_DEPTH
+          chain << {
+            class: current.class.name,
+            message: ContextFilter.filter_message(current.message),
+            backtrace: ContextFilter.filter_backtrace(current.backtrace)
+          }
+          current = current.cause
+          depth += 1
+        end
+
+        chain.presence
+      end
+
+      def build_request_context(env)
+        return unless env
+
+        request = ActionDispatch::Request.new(env)
+        ctx = {
+          url: filtered_url(request.original_url),
+          method: request.request_method,
+          params: request.filtered_parameters,
+          headers: extract_headers(request),
+          ip: request.remote_ip
+        }
+
+        ContextFilter.filter(ctx)
+      end
+
+      def build_user_context(env)
+        ctx = RailsInformant::Current.user_context || detect_current_user(env)
+        ContextFilter.filter(ctx)
+      end
+
+      def build_environment_context
+        @_static_env ||= {
+          rails_env: Rails.env.to_s,
+          ruby_version: RUBY_VERSION,
+          rails_version: Rails::VERSION::STRING,
+          hostname: Socket.gethostname
+        }.freeze
+        @_static_env.merge(pid: Process.pid)
+      end
+
+      def group_attributes(error, severity:, context:, env:, now:)
+        {
+          error_class: error.class.name, severity:,
+          message: ContextFilter.filter_message(error.message),
+          first_backtrace_line: Fingerprint.first_app_frame(error),
+          controller_action: extract_controller_action(env, context),
+          job_class: extract_job_class(context),
+          first_seen_at: now, last_seen_at: now,
+          total_occurrences: 1, created_at: now, updated_at: now
+        }
+      end
+
+      def occurrence_attributes(error, env:, context:)
+        {
+          backtrace: ContextFilter.filter_backtrace(error.backtrace),
+          exception_chain: build_exception_chain(error),
+          request_context: build_request_context(env),
+          user_context: build_user_context(env),
+          custom_context: ContextFilter.filter(RailsInformant::Current.custom_context),
+          environment_context: build_environment_context,
+          breadcrumbs: BreadcrumbBuffer.current.flush,
+          git_sha: RailsInformant.current_git_sha
+        }
+      end
+
+      def extract_controller_action(env, context)
+        if env
+          params = env["action_dispatch.request.parameters"]
+          "#{params["controller"]}##{params["action"]}" if params&.key?("controller") && params&.key?("action")
+        elsif context[:controller] && context[:action]
+          "#{context[:controller]}##{context[:action]}"
+        end
+      end
+
+      def extract_job_class(context)
+        context.dig(:job, :class) || context[:job_class]
+      end
+
+      def filtered_url(url)
+        uri = URI.parse(url)
+        if uri.query.present?
+          params = Rack::Utils.parse_query(uri.query)
+          filtered = ContextFilter.filter(params)
+          uri.query = Rack::Utils.build_query(filtered)
+        end
+        uri.to_s
+      rescue URI::InvalidURIError
+        url.split("?").first
+      end
+
+      private
+
+      def detect_current_user(env)
+        if defined?(::Current) && ::Current.respond_to?(:user) && ::Current.user
+          user_context ::Current.user
+        elsif env && env["warden"]&.user
+          user_context env["warden"].user
+        end
+      end
+
+      def extract_headers(request)
+        headers = {}
+        request.headers.each do |key, value|
+          next unless key.start_with?("HTTP_")
+          next if SKIP_HEADERS.include?(key)
+          header_name = key.delete_prefix("HTTP_").split("_").map(&:capitalize).join("-")
+          headers[header_name] = value
+        end
+        headers
+      end
+
+      def user_context(user)
+        return nil unless user
+
+        ctx = { id: user.id, class: user.class.name }
+        ctx[:email] = user.email if RailsInformant.capture_user_email && user.respond_to?(:email)
+        ctx
+      end
+    end
+  end
+end

data/lib/rails_informant/context_filter.rb

@@ -0,0 +1,45 @@
+module RailsInformant
+  class ContextFilter
+    MAX_BACKTRACE_FRAMES = 200
+    MAX_MESSAGE_LENGTH = 2000
+    MAX_CONTEXT_SIZE = 64 * 1024 # 64 KB
+
+    class << self
+      def reset!
+        @_parameter_filter = nil
+      end
+
+      def filter(context)
+        return nil unless context
+
+        filtered = parameter_filter.filter(context)
+        truncate_to_size(filtered)
+      end
+
+      def filter_backtrace(backtrace)
+        return nil unless backtrace
+        backtrace.first(MAX_BACKTRACE_FRAMES)
+      end
+
+      def filter_message(message)
+        return nil unless message
+        message.to_s.truncate(MAX_MESSAGE_LENGTH)
+      end
+
+      private
+
+      def parameter_filter
+        @_parameter_filter ||= ActiveSupport::ParameterFilter.new(Rails.application.config.filter_parameters)
+      end
+
+      def truncate_to_size(data)
+        return data if data.is_a?(Hash) && data.size < 20
+
+        json = data.to_json
+        return data if json.bytesize <= MAX_CONTEXT_SIZE
+
+        { _truncated: true, _original_size: json.bytesize }
+      end
+    end
+  end
+end

data/lib/rails_informant/current.rb

@@ -0,0 +1,5 @@
+module RailsInformant
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :breadcrumbs, :user_context, :custom_context
+  end
+end

data/lib/rails_informant/engine.rb

@@ -0,0 +1,86 @@
+module RailsInformant
+  class Engine < ::Rails::Engine
+    isolate_namespace RailsInformant
+
+    initializer "rails_informant.error_subscriber" do
+      next unless RailsInformant.capture_errors
+
+      Rails.error.subscribe RailsInformant::ErrorSubscriber.new
+    end
+
+    initializer "rails_informant.context_middleware" do
+      next unless RailsInformant.capture_errors
+
+      Rails.error.add_middleware ->(error, context) {
+        context.merge deploy_sha: RailsInformant.current_git_sha
+      }
+    end
+
+    initializer "rails_informant.middleware" do |app|
+      next unless RailsInformant.capture_errors
+
+      app.middleware.insert_before ActionDispatch::ShowExceptions,
+        RailsInformant::Middleware::ErrorCapture
+      app.middleware.insert_after ActionDispatch::DebugExceptions,
+        RailsInformant::Middleware::RescuedExceptionInterceptor
+    end
+
+    initializer "rails_informant.breadcrumbs" do
+      next unless RailsInformant.capture_errors
+
+      RailsInformant::BreadcrumbSubscriber.subscribe!
+    end
+
+    initializer "rails_informant.structured_events" do
+      next unless RailsInformant.capture_errors
+
+      Rails.event.subscribe(
+        RailsInformant::StructuredEventSubscriber.new
+      )
+    end
+
+    initializer "rails_informant.detect_deploy" do
+      config.after_initialize do
+        next unless RailsInformant.server_mode?
+
+        current_sha = RailsInformant.current_git_sha
+        next unless current_sha
+
+        now = Time.current
+        RailsInformant::ErrorGroup
+          .where(status: "fix_pending")
+          .where.not(original_sha: current_sha)
+          .in_batches(of: 100)
+          .update_all(status: "resolved", resolved_at: now, fix_deployed_at: now, updated_at: now)
+      rescue ActiveRecord::StatementInvalid
+        # Table may not exist yet during initial migration
+      end
+    end
+
+    initializer "rails_informant.validate_api_token" do
+      config.after_initialize { RailsInformant::Engine.validate_api_token! }
+    end
+
+    MINIMUM_TOKEN_LENGTH = 32
+
+    def self.validate_api_token!
+      return unless RailsInformant.capture_errors
+
+      token = RailsInformant.api_token
+
+      if token.nil?
+        raise <<~MSG.squish
+          RailsInformant: api_token must be configured when capture_errors is enabled.
+          Set it in your initializer: config.api_token = "your-secret-token"
+        MSG
+      end
+
+      if token.length < MINIMUM_TOKEN_LENGTH
+        raise <<~MSG.squish
+          RailsInformant: api_token must be at least #{MINIMUM_TOKEN_LENGTH} characters.
+          Use SecureRandom.hex(32) or Rails credentials to generate a secure token.
+        MSG
+      end
+    end
+  end
+end

data/lib/rails_informant/error_recorder.rb

@@ -0,0 +1,47 @@
+module RailsInformant
+  class ErrorRecorder
+    MAX_OCCURRENCES_PER_GROUP = 25
+    OCCURRENCE_COOLDOWN = 5 # seconds
+
+    class << self
+      def record(error, severity: "error", context: {}, source: nil, env: nil)
+        return unless RailsInformant.initialized?
+        now = Time.current
+        attrs = ContextBuilder.group_attributes(error, severity:, context:, env:, now:)
+        group = ErrorGroup.find_or_create_for(Fingerprint.generate(error), attrs)
+        group.detect_regression!
+        store_occurrence(group, error, env:, context:) if should_store_occurrence?(group)
+        notify(group)
+      rescue StandardError => e
+        Rails.logger.error "[RailsInformant] Capture failed: #{e.class}: #{e.message}\n#{e.backtrace&.first(5)&.join("\n")}"
+      end
+
+      private
+
+      def should_store_occurrence?(group)
+        return true if group.total_occurrences <= 1
+        return true unless group.last_occurrence_stored_at
+        group.last_occurrence_stored_at.before?(OCCURRENCE_COOLDOWN.seconds.ago)
+      end
+
+      def store_occurrence(group, error, env:, context:)
+        now = Time.current
+        ErrorGroup.transaction do
+          group.occurrences.create! ContextBuilder.occurrence_attributes(error, env:, context:)
+          ErrorGroup.where(id: group.id).update_all last_occurrence_stored_at: now, updated_at: now
+          group.last_occurrence_stored_at = now
+        end
+        trim_occurrences(group) if group.total_occurrences > MAX_OCCURRENCES_PER_GROUP
+      end
+
+      def trim_occurrences(group)
+        keep_ids = group.occurrences.order(created_at: :desc).limit(MAX_OCCURRENCES_PER_GROUP).select(:id)
+        Occurrence.where(error_group_id: group.id).where.not(id: keep_ids).delete_all
+      end
+      def notify(group)
+        return unless RailsInformant.config.notifiers.any? { it.should_notify?(group) }
+        RailsInformant::NotifyJob.perform_later group
+      end
+    end
+  end
+end

data/lib/rails_informant/error_subscriber.rb

@@ -0,0 +1,17 @@
+module RailsInformant
+  class ErrorSubscriber
+    SKIP_SOURCES = /_cache_store\.active_support\z/
+
+    def report(error, handled:, severity:, context:, source: nil)
+      return unless RailsInformant.initialized?
+      return if handled
+      return if source && SKIP_SOURCES.match?(source)
+      return if RailsInformant.ignored_exception?(error)
+      return if RailsInformant.already_captured?(error)
+
+      RailsInformant.mark_captured!(error)
+
+      ErrorRecorder.record error, severity:, context:, source:
+    end
+  end
+end

data/lib/rails_informant/fingerprint.rb

@@ -0,0 +1,23 @@
+require "digest"
+
+module RailsInformant
+  class Fingerprint
+    APP_FRAME_PATTERN = /\A(?!.*\/(gems|ruby|rubies)\/)/.freeze
+
+    def self.generate(exception)
+      return Digest::SHA256.hexdigest(exception.class.name) unless exception.backtrace
+
+      first_frame = first_app_frame(exception)
+      normalized = normalize_frame(first_frame)
+      Digest::SHA256.hexdigest "#{exception.class.name}:#{normalized}"
+    end
+
+    def self.first_app_frame(exception)
+      exception.backtrace.find { APP_FRAME_PATTERN.match?(it) } || exception.backtrace.first
+    end
+
+    def self.normalize_frame(frame)
+      frame.sub(/:(\d+)(?=:in |$)/, ":0")
+    end
+  end
+end

data/lib/rails_informant/mcp/base_tool.rb

@@ -0,0 +1,38 @@
+module RailsInformant
+  module Mcp
+    class BaseTool < ::MCP::Tool
+      class << self
+        private
+
+        def client_for(server_context:, environment: nil)
+          config = server_context[:config]
+          env = environment || config.default_environment
+          config.client_for(env)
+        end
+
+        def with_client(server_context:, environment: nil)
+          client = client_for(server_context:, environment:)
+          yield client
+        rescue Client::Error => e
+          error_response(e.message)
+        end
+
+        def text_response(data)
+          text = data.is_a?(String) ? data : JSON.generate(data)
+          ::MCP::Tool::Response.new([ { type: "text", text: } ])
+        end
+
+        def error_response(message)
+          ::MCP::Tool::Response.new([ { type: "text", text: message } ], error: true)
+        end
+
+        def paginated_text_response(result)
+          response_text = JSON.generate(result["data"])
+          meta = result["meta"]
+          response_text += "\n\nPage #{meta["page"]}, per_page: #{meta["per_page"]}, has_more: #{meta["has_more"]}" if meta
+          text_response(response_text)
+        end
+      end
+    end
+  end
+end

data/lib/rails_informant/mcp/client.rb

@@ -0,0 +1,123 @@
+require "net/http"
+require "json"
+require "uri"
+
+module RailsInformant
+  module Mcp
+    class Client
+      Error = Class.new(StandardError)
+
+      METHODS = {
+        delete: Net::HTTP::Delete,
+        get: Net::HTTP::Get,
+        patch: Net::HTTP::Patch,
+        post: Net::HTTP::Post
+      }.freeze
+
+      def initialize(url:, token:, allow_insecure: false, path_prefix: "/informant")
+        @base_url = url.chomp("/")
+        @token = token
+        @allow_insecure = allow_insecure
+        @path_prefix = path_prefix.chomp("/")
+        @_base_uri = URI.parse(@base_url)
+        validate_url!
+      end
+
+      def list_errors(status: nil, error_class: nil, q: nil, since: nil, page: nil, per_page: nil, controller_action: nil, job_class: nil, severity: nil, **extra)
+        params = { controller_action:, error_class:, job_class:, q:, severity:, since:, status:, page:, per_page: }
+        params[:until] = extra[:until] if extra[:until]
+        perform :get, "#{@path_prefix}/api/v1/errors", params: params.compact
+      end
+
+      def get_error(id)
+        perform :get, "#{@path_prefix}/api/v1/errors/#{Integer(id)}"
+      end
+
+      def update_error(id, params)
+        perform :patch, "#{@path_prefix}/api/v1/errors/#{Integer(id)}", body: params
+      end
+
+      def delete_error(id)
+        perform :delete, "#{@path_prefix}/api/v1/errors/#{Integer(id)}"
+      end
+
+      def fix_pending(id, fix_sha:, original_sha:, fix_pr_url: nil)
+        perform :patch, "#{@path_prefix}/api/v1/errors/#{Integer(id)}/fix_pending", body: { fix_sha:, original_sha:, fix_pr_url: }.compact
+      end
+
+      def mark_duplicate(id, duplicate_of_id:)
+        perform :patch, "#{@path_prefix}/api/v1/errors/#{Integer(id)}/duplicate", body: { duplicate_of_id: }
+      end
+
+      def list_occurrences(error_group_id: nil, since: nil, page: nil, per_page: nil, **extra)
+        params = { error_group_id:, since:, page:, per_page: }
+        params[:until] = extra[:until] if extra[:until]
+        perform :get, "#{@path_prefix}/api/v1/occurrences", params: params.compact
+      end
+
+      def status
+        perform :get, "#{@path_prefix}/api/v1/status"
+      end
+
+      private
+
+      def validate_url!
+        return if @allow_insecure
+        raise Error, "HTTPS required. Use --allow-insecure for local development." unless @_base_uri.scheme == "https"
+      end
+
+      def perform(method, path, params: {}, body: nil)
+        uri = build_uri(path, params)
+        klass = METHODS.fetch(method) { raise ArgumentError, "Unsupported HTTP method: #{method}" }
+        req = klass.new(uri)
+        if body
+          req.body = JSON.generate(body)
+          req["Content-Type"] = "application/json"
+        end
+        execute(req)
+      end
+
+      def build_uri(path, params = {})
+        uri = URI.parse("#{@base_url}#{path}")
+        uri.query = URI.encode_www_form(params) unless params.empty?
+        uri
+      end
+
+      def connection
+        @_connection ||= begin
+          http = Net::HTTP.new(@_base_uri.host, @_base_uri.port)
+          http.use_ssl = @_base_uri.scheme == "https"
+          http.open_timeout = 5
+          http.read_timeout = 10
+          http.start
+        end
+      end
+
+      def execute(req)
+        req["Authorization"] = "Bearer #{@token}"
+
+        response = connection.request(req)
+
+        case response
+        when Net::HTTPSuccess
+          response.body&.empty? ? nil : JSON.parse(response.body)
+        when Net::HTTPUnauthorized
+          raise Error, "Authentication failed. Check your API token."
+        when Net::HTTPNotFound
+          raise Error, "Not found (404)"
+        else
+          body = JSON.parse(response.body)
+          raise Error, body["error"] || "HTTP #{response.code}"
+        end
+      rescue JSON::ParserError
+        raise Error, "HTTP #{response.code}: #{response.body.to_s[0, 200]}"
+      rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, SocketError => e
+        @_connection = nil
+        raise Error, "Connection failed: #{e.message}"
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        @_connection = nil
+        raise Error, "Request timed out: #{e.message}"
+      end
+    end
+  end
+end