goodsorcery 0.1.0

data/lib/goodsorcery/backtrace/paths.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  module Backtrace
+    # Turns absolute paths under the app root into app-relative ones and
+    # decides whether a frame is the app's own code.
+    class Paths
+      THIRD_PARTY = %r{(?:\A|/)(?:vendor|bundle|\.bundle|gems|node_modules)/}
+
+      attr_reader :root
+
+      def initialize(root)
+        expanded = root ? File.expand_path(root.to_s) : nil
+        @root = expanded && "#{expanded.chomp("/")}/"
+      end
+
+      def relative(path)
+        return path unless @root && path.start_with?(@root)
+
+        path.delete_prefix(@root)
+      end
+
+      def in_app?(path)
+        relative_path = app_relative(path)
+        relative_path ? !THIRD_PARTY.match?(relative_path) : false
+      end
+
+      def under_root?(path)
+        @root ? path.start_with?(@root) : false
+      end
+
+      private
+
+      def app_relative(path)
+        return nil if path.empty? || path.start_with?("<", "(")
+        return path unless path.start_with?("/")
+
+        under_root?(path) ? path.delete_prefix(@root) : nil
+      end
+    end
+  end
+end

data/lib/goodsorcery/bundler_plugin.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  # The Bundler plugin behind `plugin "goodsorcery"` in a Gemfile. Bundler
+  # loads plugins.rb from its own copy of the gem (.bundle/plugin), so this
+  # file must stay self-contained: no other gem files, no dependencies.
+  #
+  # After `bundle install` it runs the install check in a subprocess
+  # (`bundle exec ruby -e ...` in the app root, 30 s timeout), but only in
+  # development, outside CI, unless GOODSORCERY_SKIP_INSTALL_CHECK is set,
+  # and only when the Gemfile depends on goodsorcery.
+  module BundlerPlugin
+    GEM_NAME = "goodsorcery"
+    PREFIX = "[goodsorcery]"
+    TIMEOUT = 30
+    SCRIPT = 'require "goodsorcery/install_check"; GoodSorcery::InstallCheck.new.run'
+
+    def self.register
+      ::Bundler::Plugin.add_hook(::Bundler::Plugin::Events::GEM_AFTER_INSTALL_ALL) do |dependencies|
+        after_install(dependencies)
+      end
+    end
+
+    def self.after_install(dependencies, env: ENV, root: nil)
+      return unless Gate.new(env, dependencies).open?
+
+      CheckProcess.new(root: root || ::Bundler.root.to_s).run
+    rescue StandardError, ScriptError => e
+      warn("#{PREFIX} install check skipped: #{e.class}")
+    end
+
+    # Decides whether the check runs at all.
+    class Gate
+      ENV_NAMES = %w[RAILS_ENV RACK_ENV APP_ENV].freeze
+
+      def initialize(env, dependencies)
+        @env = env
+        @dependencies = Array(dependencies)
+      end
+
+      def open?
+        development? && !set?("CI") && !set?("GOODSORCERY_SKIP_INSTALL_CHECK") && depends_on_gem?
+      end
+
+      private
+
+      def development?
+        ENV_NAMES.all? { |name| !set?(name) || @env[name] == "development" }
+      end
+
+      def set?(name)
+        value = @env[name]
+        !(value.nil? || value.strip.empty?)
+      end
+
+      def depends_on_gem?
+        @dependencies.any? { |dependency| dependency_name(dependency) == GEM_NAME }
+      end
+
+      def dependency_name(dependency)
+        dependency.respond_to?(:name) ? dependency.name.to_s : dependency.to_s
+      end
+    end
+
+    # Runs the check command and kills it when it outlives the timeout.
+    class CheckProcess
+      POLL_SECONDS = 0.05
+
+      def initialize(root:, timeout: TIMEOUT, command: ["bundle", "exec", "ruby", "-e", SCRIPT], out: $stdout)
+        @root = root
+        @timeout = timeout
+        @command = command
+        @out = out
+      end
+
+      # => true when the check finished in time.
+      def run
+        pid = spawn_check
+        return true if finished?(pid)
+
+        terminate(pid)
+        @out.puts("#{PREFIX} install check timed out after #{@timeout} s and was stopped")
+        false
+      end
+
+      private
+
+      def spawn_check
+        options = { chdir: @root, in: File::NULL }
+        return Process.spawn(*@command, **options) unless bundler_loaded?
+
+        ::Bundler.with_original_env { Process.spawn(*@command, **options) }
+      end
+
+      def bundler_loaded?
+        defined?(::Bundler) && ::Bundler.respond_to?(:with_original_env)
+      end
+
+      def finished?(pid)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + @timeout
+        until Process.wait(pid, Process::WNOHANG)
+          return false if Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
+
+          sleep(POLL_SECONDS)
+        end
+        true
+      end
+
+      def terminate(pid)
+        Process.kill("KILL", pid)
+        Process.wait(pid)
+      rescue SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/goodsorcery/client.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  # Wires configuration to the event pipeline and the delivery. One client
+  # per process, built lazily; GoodSorcery.configure rebuilds its parts.
+  class Client
+    NETWORK_DELIVERIES = %i[async sync active_job].freeze
+    REPORTING_KEY = :__goodsorcery_reporting
+
+    attr_reader :config, :log
+
+    def initialize(config, log)
+      @config = config
+      @log = log
+      @lock = Monitor.new
+      @gate = EnvironmentGate.new(config)
+    end
+
+    # => the event id, or nil when nothing was sent. Never raises. An error
+    # reported while a report is being built on the same thread (from
+    # before_send, the user lookup or a logger that reports errors) is
+    # dropped instead of recursing.
+    def notify(error, **options)
+      return nil unless reporting? && !Thread.current[REPORTING_KEY]
+
+      while_reporting { report(error, options) }
+    end
+
+    # Builds, filters and runs before_send, without any gating.
+    def prepare_event(exception, options = {})
+      scope = Scope.current
+      enrich(scope)
+      pipeline.prepare(exception, options, scope)
+    end
+
+    def reporting?
+      return true if test_delivery?
+
+      @gate.enabled? && credentials_present?
+    end
+
+    def enabled?
+      @gate.enabled?
+    end
+
+    def disabled_reason
+      @gate.reason
+    end
+
+    def add_breadcrumb(message, category: "custom", level: "info", data: nil)
+      return nil unless collecting_breadcrumbs?
+
+      crumb = Event::Breadcrumb.build(message, category: category, level: level, data: data)
+      Scope.current.add_breadcrumb(crumb, config.max_breadcrumbs)
+      nil
+    rescue StandardError => e
+      log.warn_every(:breadcrumb_error, 60, "could not record a breadcrumb (#{e.class})")
+      nil
+    end
+
+    # Whether breadcrumbs are recorded at all, so integrations can skip
+    # building them.
+    def collecting_breadcrumbs?
+      config.breadcrumbs && config.max_breadcrumbs.positive? && (test_delivery? || @gate.enabled?)
+    end
+
+    def flush(timeout = 5)
+      @delivery ? @delivery.flush(timeout) : true
+    end
+
+    def shutdown(timeout = config.shutdown_timeout)
+      @delivery ? @delivery.shutdown(timeout) : true
+    end
+
+    def verify
+      Verification.run(config, transport)
+    end
+
+    def test_events
+      delivery.is_a?(Delivery::Test) ? delivery.events : []
+    end
+
+    def clear_test_events
+      delivery.clear if delivery.is_a?(Delivery::Test)
+    end
+
+    # The replaced delivery drains first, then its transport closes, both
+    # outside the lock so reporting threads never wait on the network.
+    def reconfigure(rebuild_delivery:)
+      old_delivery, old_transport = @lock.synchronize { reset_components(rebuild_delivery) }
+      old_delivery&.shutdown(config.shutdown_timeout)
+      old_transport&.close
+    end
+
+    def delivery
+      @delivery || @lock.synchronize do
+        @delivery ||= Delivery.build(config, self)
+      end
+    end
+
+    def transport
+      @transport || @lock.synchronize { @transport ||= build_transport }
+    end
+
+    def serializer
+      @serializer ||= EventSerializer.new(log)
+    end
+
+    private
+
+    def while_reporting
+      Thread.current[REPORTING_KEY] = true
+      yield
+    ensure
+      Thread.current[REPORTING_KEY] = nil
+    end
+
+    def report(error, options)
+      exception = ExceptionCoercion.coerce(error)
+      return nil if skip?(exception)
+
+      ReportedMark.mark(exception)
+      event = prepare_event(exception, options)
+      return nil unless event
+
+      delivery.deliver(event) == false ? nil : event["event_id"]
+    rescue StandardError => e
+      log.error("notify failed with #{e.class}; the error was not reported")
+      nil
+    end
+
+    def pipeline
+      @pipeline || @lock.synchronize { @pipeline ||= EventPipeline.new(config, log) }
+    end
+
+    def ignore_list
+      @ignore_list || @lock.synchronize { @ignore_list ||= IgnoreList.new(config.ignore_exceptions) }
+    end
+
+    def enrich(scope)
+      scope.enrich
+    rescue StandardError => e
+      log.warn_every(:enrich_error, 60, "could not read request or job details (#{e.class})")
+    end
+
+    def skip?(exception)
+      ReportedMark.reported?(exception) || exception.is_a?(RetryableDeliveryError) || ignore_list.ignore?(exception)
+    end
+
+    def test_delivery?
+      config.delivery == :test
+    end
+
+    def credentials_present?
+      return true unless NETWORK_DELIVERIES.include?(config.delivery)
+      return true unless config.api_key.to_s.empty?
+
+      log.warn_once(:missing_api_key,
+                    "no API key configured (GOODSORCERY_API_KEY or config.api_key); errors are not sent")
+      false
+    end
+
+    def build_transport
+      Transport.new(endpoint: config.endpoint, api_key: config.api_key, open_timeout: config.open_timeout,
+                    read_timeout: config.read_timeout, log: log)
+    end
+
+    # Returns the delivery and transport to retire, if they are being replaced.
+    def reset_components(rebuild_delivery)
+      @pipeline = nil
+      @ignore_list = nil
+      return [] unless rebuild_delivery
+
+      replaced = [@delivery, @transport]
+      @delivery = nil
+      @transport = nil
+      replaced
+    end
+  end
+end

data/lib/goodsorcery/configuration/validation.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  class Configuration
+    # Class macros that define setters which reject invalid values with a clear
+    # ArgumentError. Messages show the rejected value only for plain settings,
+    # never for credentials.
+    module Validation
+      def integer_setting(name, range)
+        define_method(:"#{name}=") do |value|
+          unless value.is_a?(Integer) && range.cover?(value)
+            raise ArgumentError, "#{name} must be an Integer in #{range} (got #{value.inspect})"
+          end
+
+          instance_variable_set(:"@#{name}", value)
+        end
+      end
+
+      def seconds_setting(name)
+        define_method(:"#{name}=") do |value|
+          unless value.is_a?(Numeric) && value.positive?
+            raise ArgumentError, "#{name} must be a positive number of seconds (got #{value.inspect})"
+          end
+
+          instance_variable_set(:"@#{name}", value)
+        end
+      end
+
+      # The message never echoes the value: an endpoint URL can carry credentials.
+      def endpoint_setting
+        define_method(:endpoint=) do |value|
+          unless value.nil? || Validation.http_url?(value)
+            raise ArgumentError, "endpoint must be an http:// or https:// URL with a host and no user:password part"
+          end
+
+          @endpoint = value
+        end
+      end
+
+      def self.http_url?(value)
+        uri = URI(value.to_s)
+        %w[http https].include?(uri.scheme) && !uri.host.to_s.empty? && uri.userinfo.nil?
+      rescue URI::InvalidURIError
+        false
+      end
+
+      def choice_setting(name, choices)
+        define_method(:"#{name}=") do |value|
+          normalized = value.is_a?(String) ? value.to_sym : value
+          unless choices.include?(normalized)
+            raise ArgumentError, "#{name} must be one of #{choices.map(&:inspect).join(", ")} (got #{value.inspect})"
+          end
+
+          instance_variable_set(:"@#{name}", normalized)
+        end
+      end
+    end
+  end
+end

data/lib/goodsorcery/configuration.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require_relative "configuration/validation"
+
+module GoodSorcery
+  # Every setting the gem reads (DESIGN.md 2 and 3). Unset credentials,
+  # endpoint, environment, release and the enabled flag fall back to
+  # environment variables (and Rails) when they are read.
+  class Configuration
+    extend Validation
+
+    DELIVERIES = %i[async sync active_job test].freeze
+    DELIVERY_SETTINGS = %i[
+      delivery api_key endpoint batch_size flush_interval max_queue_size shutdown_timeout
+      max_retries open_timeout read_timeout active_job_queue
+    ].freeze
+
+    attr_writer :api_key, :environment, :release, :logger, :root
+    attr_accessor :disabled_environments, :enabled_environments, :filter_params,
+                  :use_rails_filter_parameters, :extra_filters, :ignore_exceptions, :tags,
+                  :user_method, :send_code_context, :breadcrumbs,
+                  :report_handled_errors, :active_job_queue, :request_extractor,
+                  :send_request_params, :send_request_headers, :send_session, :send_job_arguments
+    attr_reader :delivery, :batch_size, :flush_interval, :max_queue_size,
+                :shutdown_timeout, :max_retries, :open_timeout, :read_timeout,
+                :max_breadcrumbs, :install_check, :before_send
+
+    endpoint_setting
+    choice_setting :install_check, [:verify, :test_event, false]
+    integer_setting :batch_size, 1..100
+    integer_setting :max_queue_size, 1..1_000_000
+    integer_setting :max_retries, 0..20
+    integer_setting :max_breadcrumbs, 0..100
+    seconds_setting :flush_interval
+    seconds_setting :shutdown_timeout
+    seconds_setting :open_timeout
+    seconds_setting :read_timeout
+
+    def initialize
+      assign_list_defaults
+      assign_delivery_defaults
+      assign_behaviour_defaults
+    end
+
+    def api_key
+      @api_key || EnvFlag.present("GOODSORCERY_API_KEY") || rails_credentials_api_key
+    end
+
+    def endpoint
+      (@endpoint || EnvFlag.present("GOODSORCERY_ENDPOINT") || Defaults::ENDPOINT).to_s.chomp("/")
+    end
+
+    # The endpoint without any user:password part, for logs and reports.
+    def endpoint_label
+      endpoint.sub(%r{(?<=://)[^/@]*@}, "")
+    end
+
+    def environment
+      (@environment || EnvFlag.present("GOODSORCERY_ENV") || rails_env ||
+        EnvFlag.present("RACK_ENV") || EnvFlag.present("APP_ENV") || "development").to_s
+    end
+
+    def release
+      return @release.to_s[0, ReleaseDetector::MAX_LENGTH] if @release
+
+      @detected_release = ReleaseDetector.new(root).release unless defined?(@detected_release)
+      @detected_release
+    end
+
+    # Rails.root in Rails apps, else the working directory.
+    def root
+      (@root || rails_root || Dir.pwd).to_s
+    end
+
+    # Rails.logger in Rails apps, else WARN and above to $stderr.
+    def logger
+      @logger || rails_logger || (@default_logger ||= ::Logger.new($stderr, level: ::Logger::WARN))
+    end
+
+    # The key filter's companions: Rails' filter_parameters (unless turned
+    # off), then config.extra_filters.
+    def event_filters
+      rails = use_rails_filter_parameters ? RailsFilterParameters.build : nil
+      [rails, *extra_filters].compact
+    end
+
+    def enabled
+      @enabled.nil? ? EnvFlag.parse(ENV.fetch("GOODSORCERY_ENABLED", nil)) : @enabled
+    end
+
+    def enabled=(value)
+      unless [true, false, nil].include?(value)
+        raise ArgumentError, "enabled must be true, false or nil (got #{value.inspect})"
+      end
+
+      @enabled = value
+    end
+
+    def delivery=(value)
+      @delivery = DeliverySetting.normalize(value)
+    end
+
+    def before_send=(callable)
+      unless callable.nil? || callable.respond_to?(:call)
+        raise ArgumentError, "before_send must respond to #call (or be nil)"
+      end
+
+      @before_send = callable
+    end
+
+    def masked_api_key
+      MaskedKey.new(api_key).to_s
+    end
+
+    def delivery_settings
+      DELIVERY_SETTINGS.to_h { |name| [name, public_send(name)] }
+    end
+
+    # Never shows the API key (or endpoint credentials): consoles, error
+    # pages and loggers print objects with #inspect.
+    def inspect
+      delivery_name = delivery.is_a?(Symbol) ? delivery.inspect : delivery.class.name
+      "#<#{self.class.name} api_key=#{masked_api_key} endpoint=#{endpoint_label} " \
+        "environment=#{environment} delivery=#{delivery_name}>"
+    end
+
+    private
+
+    def assign_list_defaults
+      @disabled_environments = Defaults::DISABLED_ENVIRONMENTS.dup
+      @enabled_environments = nil
+      @filter_params = Defaults::FILTER_PARAMS.dup
+      @ignore_exceptions = Defaults::IGNORE_EXCEPTIONS.dup
+      @extra_filters = []
+      @tags = {}
+    end
+
+    def assign_delivery_defaults
+      @delivery = :async
+      @batch_size = 25
+      @flush_interval = 2.0
+      @max_queue_size = 1_000
+      @shutdown_timeout = 5
+      @max_retries = 3
+      @open_timeout = 2
+      @read_timeout = 5
+      @active_job_queue = "default"
+    end
+
+    def assign_behaviour_defaults
+      @use_rails_filter_parameters = true
+      @user_method = :current_user
+      @send_code_context = true
+      @breadcrumbs = true
+      @max_breadcrumbs = 40
+      @install_check = :verify
+      @report_handled_errors = true
+      assign_capture_defaults
+    end
+
+    def assign_capture_defaults
+      @send_request_params = true
+      @send_request_headers = true
+      @send_session = true
+      @send_job_arguments = true
+    end
+
+    def rails_app?
+      defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+    end
+
+    def rails_root
+      ::Rails.root if rails_app? && ::Rails.respond_to?(:root)
+    end
+
+    def rails_logger
+      ::Rails.logger if defined?(::Rails) && ::Rails.respond_to?(:logger)
+    end
+
+    def rails_env
+      ::Rails.env.to_s if defined?(::Rails) && ::Rails.respond_to?(:env) && ::Rails.env
+    end
+
+    def rails_credentials_api_key
+      return unless rails_app?
+
+      ::Rails.application.credentials.dig(:goodsorcery, :api_key)
+    rescue StandardError
+      nil
+    end
+  end
+
+  # Normalizes and validates config.delivery.
+  module DeliverySetting
+    def self.normalize(value)
+      symbol = value.is_a?(String) ? value.to_sym : value
+      return symbol if Configuration::DELIVERIES.include?(symbol)
+      return value if !value.is_a?(Symbol) && value.respond_to?(:deliver)
+
+      raise ArgumentError, "delivery must be one of #{Configuration::DELIVERIES.map(&:inspect).join(", ")} " \
+                           "or an object responding to #deliver (got a #{value.class})"
+    end
+  end
+end

data/lib/goodsorcery/defaults.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module GoodSorcery
+  # Default lists. Configuration copies them, so apps can add with +=, remove
+  # with -= or replace them entirely.
+  module Defaults
+    # Mirrors Rails' generated filter_parameters plus the server's scrub list.
+    FILTER_PARAMS = [
+      /passw/i, /secret/i, /token/i, /_key/i, /api-?key/i, /crypt/i, /salt/i, /certificate/i,
+      /otp/i, /ssn/i, /cvv/i, /cvc/i, /authorization/i, /cookie/i, /csrf/i, /xsrf/i,
+      /session[-_]?id/i, /credit[-_]?card/i, /card[-_]?number/i, /signature/i, /email/i
+    ].freeze
+
+    # Class names (subclasses match too) that are never reported.
+    IGNORE_EXCEPTIONS = %w[
+      AbstractController::ActionNotFound
+      ActionController::BadRequest
+      ActionController::InvalidAuthenticityToken
+      ActionController::InvalidCrossOriginRequest
+      ActionController::MethodNotAllowed
+      ActionController::NotImplemented
+      ActionController::ParameterMissing
+      ActionController::RoutingError
+      ActionController::UnknownFormat
+      ActionController::UnknownHttpMethod
+      ActionDispatch::Http::MimeNegotiation::InvalidType
+      ActionDispatch::Http::Parameters::ParseError
+      ActiveRecord::RecordNotFound
+      CGI::Session::CookieStore::TamperedWithCookie
+      Rack::QueryParser::InvalidParameterError
+      Rack::QueryParser::ParameterTypeError
+      Sinatra::NotFound
+      SignalException
+      SystemExit
+    ].freeze
+
+    DISABLED_ENVIRONMENTS = %w[development test].freeze
+    ENDPOINT = "https://app.goodsorcery.com"
+  end
+end