goodsorcery 0.1.0

data/lib/goodsorcery/install_check.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require_relative "../goodsorcery"
+require_relative "status_report"
+
+module GoodSorcery
+  # Runs after `bundle install` (via the Bundler plugin) in a subprocess of
+  # the app root. Boots the app when config/environment.rb exists, so the
+  # initializer's settings apply, then reports per config.install_check:
+  # :verify (default), :test_event or false. Prints one "[goodsorcery]" line
+  # per finding and never raises.
+  class InstallCheck
+    def initialize(root: Dir.pwd, out: $stdout, env: ENV)
+      @root = root
+      @out = out
+      @env = env
+    end
+
+    def run
+      boot_app
+      check
+    rescue StandardError, ScriptError => e
+      @out.puts("#{StatusReport::PREFIX} install check failed: #{e.class}: #{one_line(e.message)}")
+      false
+    end
+
+    private
+
+    def boot_app
+      environment_file = File.join(@root, "config", "environment.rb")
+      return unless File.file?(environment_file)
+
+      @env["RAILS_ENV"] ||= "development"
+      require environment_file
+    end
+
+    def check
+      report = StatusReport.new(GoodSorcery.client, out: @out)
+      mode = GoodSorcery.configuration.install_check
+      return skipped(report) unless mode
+
+      report.print_settings
+      verified = report.print_verification
+      return verified unless mode == :test_event
+
+      report.print_test_event && verified
+    end
+
+    def skipped(report)
+      report.say("install check skipped (config.install_check = false)")
+      true
+    end
+
+    def one_line(message)
+      Text.limit(message.to_s.lines.first.to_s.strip, 200)
+    end
+  end
+end

data/lib/goodsorcery/integrations/action_cable.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Integrations
+    # The Action Cable layer (DESIGN.md 5.1), prepended into
+    # ActionCable::Channel::Base. Each subscribe, unsubscribe and action runs
+    # in a fresh scope named "ChatChannel#speak"; exceptions that escape the
+    # channel's own rescue_from handlers are reported, then re-raised.
+    module ActionCable
+      # Prepended into ActionCable::Channel::Base.
+      module Extension
+        def subscribe_to_channel
+          Integrations.run_unit_of_work(ChannelAction.new(self, "subscribed")) { super }
+        end
+
+        def unsubscribe_from_channel
+          Integrations.run_unit_of_work(ChannelAction.new(self, "unsubscribed")) { super }
+        end
+
+        def perform_action(data)
+          Integrations.run_unit_of_work(ChannelAction.new(self, ChannelAction.action_name(data), data)) { super }
+        end
+      end
+
+      def self.install(base = ::ActionCable::Channel::Base)
+        base.prepend(Extension) unless base <= Extension
+      end
+
+      # One channel action. The request section (the connection's request,
+      # with the subscription params and action data as params) is read only
+      # when an error is reported.
+      class ChannelAction
+        def self.action_name(data)
+          name = data.is_a?(Hash) ? data["action"].to_s : ""
+          name.empty? ? "receive" : name
+        end
+
+        def initialize(channel, action, data = nil)
+          @channel = channel
+          @action = action
+          @data = data
+        end
+
+        def open(scope)
+          scope.transaction = "#{@channel.class.name}##{@action}"
+          scope.enricher = self
+        end
+
+        def enrich(scope)
+          scope.request ||= request_section
+        end
+
+        private
+
+        def request_section
+          env = @channel.connection.respond_to?(:env) ? @channel.connection.env : nil
+          section = env ? connection_request(env) : {}
+          section["params"] = params if GoodSorcery.configuration.send_request_params
+          section.compact
+        end
+
+        def connection_request(env)
+          details = GoodSorcery::Rack::RequestDetails.new(env, GoodSorcery.configuration)
+          { "url" => details.url, "request_id" => details.request_id, "remote_ip" => details.remote_ip,
+            "headers" => details.headers }
+        end
+
+        def params
+          channel_params = @channel.params
+          { "channel" => channel_params.is_a?(Hash) ? channel_params.to_h : nil, "data" => @data }.compact
+        end
+      end
+    end
+  end
+end

data/lib/goodsorcery/integrations/active_job/job_details.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Integrations
+    module ActiveJob
+      # The "job" section, transaction and queue tag for one Active Job
+      # execution, read when an error is reported (arguments are deserialized
+      # by then). Action Mailer deliveries (deliver_later) are named
+      # "UserMailer#welcome" and carry the mailer method's args and params.
+      class JobDetails
+        def initialize(job)
+          @job = job
+        end
+
+        def open(scope)
+          scope.merge_tags("queue" => @job.queue_name)
+          scope.enricher = self
+        end
+
+        def enrich(scope)
+          mail = MailDelivery.for(@job)
+          scope.transaction ||= mail ? mail.transaction : @job.class.name
+          scope.job = to_h(mail)
+        end
+
+        def to_h(mail = MailDelivery.for(@job))
+          section = execution_fields.merge(timestamps)
+          section.merge!(mail.to_h) if mail
+          section["arguments"] = arguments(mail) if send_arguments?
+          section.compact
+        end
+
+        private
+
+        def execution_fields
+          {
+            "framework" => "active_job", "class" => @job.class.name, "id" => @job.job_id,
+            "provider_job_id" => @job.provider_job_id&.to_s, "queue" => @job.queue_name,
+            "priority" => @job.priority, "executions" => @job.executions
+          }
+        end
+
+        def timestamps
+          scheduled = @job.respond_to?(:scheduled_at) ? @job.scheduled_at : nil
+          {
+            "enqueued_at" => Event::Fields.iso_time(@job.enqueued_at),
+            "scheduled_at" => Event::Fields.iso_time(scheduled)
+          }
+        end
+
+        def send_arguments?
+          GoodSorcery.configuration.send_job_arguments && @job.class.goodsorcery_send_arguments
+        end
+
+        def arguments(mail)
+          JobArguments.new.serialize(mail ? mail.arguments : @job.arguments)
+        end
+      end
+
+      # ActionMailer::MailDeliveryJob's arguments:
+      # [mailer, method, delivery_method, { args:, kwargs:, params: }].
+      class MailDelivery
+        def self.for(job)
+          return nil unless defined?(::ActionMailer::MailDeliveryJob) && job.is_a?(::ActionMailer::MailDeliveryJob)
+
+          new(job.arguments)
+        end
+
+        def initialize(arguments)
+          mailer, action, _delivery_method, options = arguments
+          @mailer = mailer.to_s
+          @action = action.to_s
+          @options = options.is_a?(Hash) ? options : {}
+        end
+
+        def transaction
+          "#{@mailer}##{@action}"
+        end
+
+        def to_h
+          { "mailer" => @mailer, "action" => @action }
+        end
+
+        def arguments
+          { "args" => @options[:args], "kwargs" => @options[:kwargs], "params" => @options[:params] }.compact
+        end
+      end
+    end
+  end
+end

data/lib/goodsorcery/integrations/active_job.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "active_job/job_details"
+
+module GoodSorcery
+  module Integrations
+    # The Active Job layer (DESIGN.md 5.1), prepended into ActiveJob::Base.
+    # It wraps perform_now, outside the job's own rescue_from/retry_on
+    # handling, so an error is reported once, when it escapes the job (after
+    # the last retry), not on every attempt the job handles itself.
+    module ActiveJob
+      # Prepended into ActiveJob::Base.
+      module Extension
+        def self.prepended(base)
+          base.class_attribute :goodsorcery_send_arguments, instance_accessor: false, default: true
+          base.extend(ClassMethods)
+        end
+
+        # Class macro: `goodsorcery_arguments false` never sends this job's
+        # arguments (inherited by subclasses).
+        module ClassMethods
+          def goodsorcery_arguments(enabled)
+            self.goodsorcery_send_arguments = enabled ? true : false
+          end
+        end
+
+        def perform_now
+          return super if Integrations.delivery_job?(self)
+
+          Integrations.run_unit_of_work(JobDetails.new(self)) { super }
+        end
+      end
+
+      def self.install(base = ::ActiveJob::Base)
+        base.prepend(Extension) unless base <= Extension
+      end
+    end
+  end
+end

data/lib/goodsorcery/integrations/rails/controller_action.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Integrations
+    module Rails
+      # The controller and action handling a request, from the controller
+      # instance when Rails dispatched to one, else from the router's path
+      # parameters.
+      class ControllerAction
+        attr_reader :controller, :action
+
+        def self.from_env(env)
+          instance = env["action_controller.instance"]
+          return new(instance.class.name, instance.action_name) if instance.respond_to?(:action_name)
+
+          from_path_parameters(env["action_dispatch.request.path_parameters"])
+        end
+
+        def self.from_path_parameters(params)
+          return nil unless params.is_a?(Hash) && params[:controller] && params[:action]
+
+          new("#{::ActiveSupport::Inflector.camelize(params[:controller].to_s)}Controller", params[:action].to_s)
+        end
+
+        def initialize(controller, action)
+          @controller = controller.to_s
+          @action = action.to_s
+        end
+
+        def transaction
+          "#{controller}##{action}"
+        end
+
+        def to_h
+          { "controller" => controller, "action" => action }
+        end
+      end
+    end
+  end
+end

data/lib/goodsorcery/integrations/rails/controller_enricher.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Integrations
+    module Rails
+      # The Action Controller layer (DESIGN.md 5.1): the Rack request plus the
+      # transaction ("UsersController#update"), context.controller and the
+      # signed-in user. Runs only when an error is reported.
+      class ControllerEnricher < GoodSorcery::Rack::RequestEnricher
+        def enrich(scope)
+          super
+          add_controller(scope, ControllerAction.from_env(@env))
+          scope.user ||= UserLookup.new(GoodSorcery.configuration.user_method).find(@env["action_controller.instance"])
+        end
+
+        private
+
+        def add_controller(scope, action)
+          return unless action
+
+          scope.transaction ||= action.transaction
+          scope.merge_context("controller" => action.to_h)
+        end
+      end
+    end
+  end
+end

data/lib/goodsorcery/integrations/rails/error_subscriber.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Integrations
+    module Rails
+      # Subscribed to Rails.error. Unhandled errors are reported at level
+      # "error"; handled ones (Rails.error.handle/report) at their severity,
+      # unless report_handled_errors is false. The reporter's context goes to
+      # context.rails_error (filtered like any context), with the source.
+      class ErrorSubscriber
+        LEVELS = { error: "error", warning: "warning", info: "info" }.freeze
+
+        def report(error, handled:, severity: nil, context: {}, source: nil)
+          return if handled && !GoodSorcery.configuration.report_handled_errors
+          return if ReportedMark.reported?(error) || from_delivery_job?(context)
+
+          GoodSorcery.notify(error, level: level(handled, severity),
+                                    context: { "rails_error" => rails_error_context(context, source) })
+        end
+
+        private
+
+        def level(handled, severity)
+          handled ? LEVELS.fetch(severity.to_s.to_sym, "warning") : "error"
+        end
+
+        def from_delivery_job?(context)
+          context.is_a?(Hash) && Integrations.delivery_job?(context[:job])
+        end
+
+        # Controllers and jobs from Rails' execution context become
+        # "#<ClassName>"; records become GlobalID strings.
+        def rails_error_context(context, source)
+          details = context.is_a?(Hash) ? JobArguments.new.serialize(context) : {}
+          details.merge("source" => source&.to_s).compact
+        end
+      end
+    end
+  end
+end

data/lib/goodsorcery/integrations/rails/notification_breadcrumbs.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Integrations
+    module Rails
+      # Turns ActiveSupport::Notifications events into breadcrumbs, recorded
+      # only inside a scope an integration opened (a request, job or channel
+      # action). Never raises into the instrumented code.
+      class NotificationBreadcrumbs
+        EVENTS = %w[
+          start_processing.action_controller sql.active_record perform.active_job deliver.action_mailer
+        ].freeze
+        IGNORED_SQL_NAMES = %w[SCHEMA CACHE TRANSACTION].freeze
+
+        def self.subscribe
+          return if @subscribed
+
+          @subscribed = true
+          recorder = new
+          EVENTS.each do |event_name|
+            ::ActiveSupport::Notifications.subscribe(event_name) do |name, started, finished, _id, payload|
+              recorder.record_notification(name, started, finished, payload)
+            end
+          end
+        end
+
+        def record_notification(name, started, finished, payload)
+          return unless Scope.unit_of_work && GoodSorcery.client.collecting_breadcrumbs?
+
+          record(name, payload, duration_ms(started, finished))
+        rescue StandardError
+          nil
+        end
+
+        private
+
+        def record(name, payload, duration)
+          case name
+          when "start_processing.action_controller" then controller(payload)
+          when "sql.active_record" then sql(payload, duration)
+          when "perform.active_job" then job(payload)
+          when "deliver.action_mailer" then mail(payload)
+          end
+        end
+
+        def controller(payload)
+          format = payload[:format].to_s.upcase
+          message = "#{payload[:controller]}##{payload[:action]}"
+          GoodSorcery.add_breadcrumb(format.empty? ? message : "#{message} as #{format}", category: "controller")
+        end
+
+        def sql(payload, duration)
+          return if payload[:cached] || IGNORED_SQL_NAMES.include?(payload[:name])
+
+          statement = SqlStatement.new(payload[:sql]).obfuscated
+          GoodSorcery.add_breadcrumb("#{payload[:name] || "SQL"} (#{duration}ms)", category: "sql",
+                                                                                   data: { "sql" => statement })
+        end
+
+        def job(payload)
+          job = payload[:job]
+          return unless job
+
+          failure = payload[:exception_object]
+          message = failure ? "#{job.class.name} failed (#{failure.class})" : "Performed #{job.class.name}"
+          GoodSorcery.add_breadcrumb(message, category: "job", level: failure ? "error" : "info",
+                                              data: { "queue" => job.queue_name })
+        end
+
+        def mail(payload)
+          GoodSorcery.add_breadcrumb("Delivered mail from #{payload[:mailer]}", category: "custom")
+        end
+
+        def duration_ms(started, finished)
+          ((finished - started) * 1000).round(1)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/goodsorcery/integrations/rails/sql_statement.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Integrations
+    module Rails
+      # The SQL text recorded in a breadcrumb, with literal values replaced by
+      # "?": quoted strings (also dollar-quoted, and one cut off by the length
+      # cap) and numbers. Adapters that inline values instead of using bind
+      # parameters (mysql2, prepared_statements: false, sanitize_sql) would
+      # otherwise send emails, tokens or password digests unfiltered.
+      # Identifiers, keywords and placeholders such as $1 stay readable.
+      class SqlStatement
+        MAX_LENGTH = 1_000
+        # A dollar-quoted string ($$…$$, $tag$…$tag$) or a quoted one; the
+        # leftmost wins, so "$" inside a quoted string is not a dollar quote.
+        LITERAL = /\$((?:[a-z_]\w*)?)\$.*?(?:\$\1\$|\z)|'(?:[^'\\]|\\.|'')*(?:'|\z)/im
+        NUMBER = /(?<![\w$])\d+(?:\.\d+)?(?:e[+-]?\d+)?/i
+        PLACEHOLDER = "?"
+
+        def initialize(sql)
+          @sql = sql.to_s
+        end
+
+        # The first MAX_LENGTH characters, without literal values.
+        def obfuscated
+          Text.limit(@sql, MAX_LENGTH).gsub(LITERAL, PLACEHOLDER).gsub(NUMBER, PLACEHOLDER)
+        end
+      end
+    end
+  end
+end

data/lib/goodsorcery/integrations/rails/user_lookup.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Integrations
+    module Rails
+      # Finds the signed-in user for a report: the controller's user_method
+      # (default current_user), else Current.user. Keeps only id, email,
+      # username and name. Anything the app raises while looking is ignored.
+      class UserLookup
+        def initialize(user_method)
+          @user_method = user_method
+        end
+
+        def find(controller)
+          user = from_controller(controller) || from_current_attributes
+          user && Event::UserSection.build(user)
+        end
+
+        private
+
+        def from_controller(controller)
+          return nil unless controller && @user_method && controller.respond_to?(@user_method, true)
+
+          controller.send(@user_method)
+        rescue StandardError
+          nil
+        end
+
+        def from_current_attributes
+          return nil unless defined?(::Current) && ::Current.respond_to?(:user)
+
+          ::Current.user
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/goodsorcery/integrations/rails.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "../integrations"
+require_relative "rails/controller_action"
+require_relative "rails/user_lookup"
+require_relative "rails/controller_enricher"
+require_relative "rails/error_subscriber"
+require_relative "rails/sql_statement"
+require_relative "rails/notification_breadcrumbs"
+
+module GoodSorcery
+  module Integrations
+    # Wiring for the Rails layers; GoodSorcery::Railtie calls these.
+    module Rails
+      module_function
+
+      def install_middleware(middleware)
+        middleware.insert_after(::ActionDispatch::ShowExceptions, GoodSorcery::Rack::Middleware,
+                                enricher: ControllerEnricher)
+      end
+
+      def install_framework_hooks
+        ::ActiveSupport.on_load(:active_job) do
+          require_relative "active_job"
+          GoodSorcery::Integrations::ActiveJob.install(self)
+        end
+        ::ActiveSupport.on_load(:action_cable_channel) do
+          require_relative "action_cable"
+          GoodSorcery::Integrations::ActionCable.install(self)
+        end
+      end
+
+      # After the app's initializers ran: subscribe to Rails.error and to
+      # notifications, hook Sidekiq, and recompile the filters so the final
+      # filter_parameters apply.
+      def after_initialize
+        subscribe_to_error_reporter
+        NotificationBreadcrumbs.subscribe if GoodSorcery.configuration.breadcrumbs
+        install_sidekiq if defined?(::Sidekiq)
+        GoodSorcery.client.reconfigure(rebuild_delivery: false)
+      end
+
+      def subscribe_to_error_reporter
+        return if @error_subscriber || !::Rails.respond_to?(:error)
+
+        @error_subscriber = ErrorSubscriber.new
+        ::Rails.error.subscribe(@error_subscriber)
+      end
+
+      def install_sidekiq
+        require_relative "sidekiq"
+        Integrations::Sidekiq.install
+      end
+    end
+  end
+end

data/lib/goodsorcery/integrations/rake.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "../integrations"
+
+module GoodSorcery
+  module Integrations
+    # Rake: an exception that ends the rake process is reported with
+    # transaction "rake <top-level tasks>" and context.rake (the failing task
+    # and its arguments), then the queue is flushed (up to shutdown_timeout)
+    # before Rake prints the error and exits.
+    module Rake
+      IVAR = :@__goodsorcery_rake_task
+
+      def self.install
+        ::Rake::Task.prepend(TaskExtension) unless ::Rake::Task <= TaskExtension
+        ::Rake::Application.prepend(ApplicationExtension) unless ::Rake::Application <= ApplicationExtension
+      end
+
+      # Remembers the innermost task an exception escaped from.
+      module TaskExtension
+        def execute(args = nil)
+          super
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          FailedTask.remember(e, self, args)
+          raise
+        end
+      end
+
+      # Reports the exception before Rake displays it and exits.
+      module ApplicationExtension
+        def display_error_message(exception)
+          FailedTask.report(exception, top_level_tasks)
+          super
+        end
+      end
+
+      # The task (name and arguments) an exception escaped from.
+      module FailedTask
+        module_function
+
+        def remember(exception, task, args)
+          return if exception.frozen? || exception.instance_variable_defined?(IVAR)
+
+          arguments = args.respond_to?(:to_h) ? args.to_h : {}
+          exception.instance_variable_set(IVAR, { "task" => task.name, "arguments" => arguments })
+        rescue StandardError
+          nil
+        end
+
+        def report(exception, top_level_tasks)
+          rake = exception.instance_variable_defined?(IVAR) ? exception.instance_variable_get(IVAR) : nil
+          GoodSorcery.notify(exception, transaction: transaction(top_level_tasks),
+                                        context: rake ? { "rake" => rake } : nil)
+          GoodSorcery.flush(GoodSorcery.configuration.shutdown_timeout)
+        rescue StandardError
+          nil
+        end
+
+        # Task arguments ("db:seed[a,b]") stay out of the transaction name;
+        # they are sent, filtered, in context.rake.
+        def transaction(top_level_tasks)
+          names = Array(top_level_tasks).map { |name| name.to_s.sub(/\[.*\z/m, "") }
+          "rake #{names.join(" ")}".strip
+        end
+      end
+    end
+  end
+end