devbench 0.5.0

data/lib/devbench/identity.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'current'
+
+module Devbench
+  # Who was affected (docs/SERVER_SDK_SPEC.md, Capability 5).
+  #
+  # Identity travels in its own field of every control message and nowhere
+  # else: never in a message, a symbol or a log line, so it can never move a
+  # fingerprint.
+  module Identity
+    MAX = 255
+
+    # Returns a frozen {email:, account:} hash with empty fields dropped, or
+    # nil when neither is present.
+    def self.normalize(email, account)
+      user = {}
+
+      email = text(email).strip.downcase
+      user[:email] = email[0, MAX] unless email.empty?
+
+      account = text(account).strip
+      user[:account] = account[0, MAX] unless account.empty?
+
+      user.empty? ? nil : user.freeze
+    end
+
+    # An identity that cannot be read is dropped rather than raised: this is
+    # called from a before_action, and a raise there fails the request.
+    def self.text(value)
+      return '' if value.nil?
+
+      value.to_s.encode('UTF-8', invalid: :replace, undef: :replace).scrub
+    rescue StandardError, SystemStackError
+      ''
+    end
+    private_class_method :text
+  end
+
+  # Records who the current request is for. Call once per request, typically
+  # from a before_action; Devbench::Middleware clears it when the request ends.
+  #
+  #   Devbench.set_user(email: current_user.email, account: current_account.id)
+  #
+  # Each field is optional. Calling again replaces the whole identity, and
+  # calling with neither clears it. Never raises.
+  def self.set_user(email: nil, account: nil)
+    Current.user = Identity.normalize(email, account)
+    nil
+  rescue StandardError, SystemStackError
+    nil
+  end
+end

data/lib/devbench/middleware.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require_relative 'trace'
+require_relative 'current'
+require_relative 'reporter'
+
+module Devbench
+  # Rack middleware: accepts the correlation id and makes it available for the
+  # duration of the request, and reports exceptions that escape the app.
+  #
+  # Never rejects a request, never alters the response body, and never raises
+  # anything of its own. An exception from the application is reported and
+  # then re-raised — the same object, backtrace intact — so whatever sits
+  # outside this middleware sees exactly what it would have without it. A
+  # diagnostics middleware that can fail a request is worse than no
+  # diagnostics.
+  #
+  #   config.middleware.insert_before 0, Devbench::Middleware
+  class Middleware
+    HANDLED_HEADER = 'x-adt-handled'
+    EXPOSE_HEADER = 'Access-Control-Expose-Headers'
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      # DEVBENCH_ENABLED=false: not even the trace scope or the header.
+      return @app.call(env) unless Devbench.enabled?
+
+      trace = begin
+        Trace.parse(env[Trace::RACK_HEADER])
+      rescue StandardError
+        nil
+      end
+
+      # Scoped even without a trace: identity set during this request must
+      # end with it, and a thread's next request must not inherit it.
+      status, headers, body = Current.with(trace) do
+        result = begin
+          @app.call(env)
+        rescue Exception => e # rubocop:disable Lint/RescueException
+          # Reported inside the scope so the report carries this request's
+          # trace and user. capture never raises; if it somehow did, the
+          # application's exception would be lost, which is the one outcome
+          # this must not have.
+          report(e, env)
+          raise e
+        end
+
+        # Rails' ShowExceptions turns an exception into a 500 page itself, so
+        # nothing escapes to here. It leaves the exception in env.
+        report(env['action_dispatch.exception'], env)
+
+        trace.nil? ? result : mark_handled(result)
+      end
+
+      [status, headers, body]
+    end
+
+    private
+
+    def report(error, env)
+      return if error.nil?
+
+      Reporter.capture(error, context: 'request', handled: false, symbol: symbol(env))
+    rescue Exception # rubocop:disable Lint/RescueException
+      nil
+    end
+
+    # Controller#action, when Rails has said which. The controller instance
+    # knows its own class name exactly (acronym inflections included); the
+    # path parameters are the fallback when the error happened before it ran.
+    def symbol(env)
+      controller = env['action_controller.instance']
+      if controller.respond_to?(:action_name) && controller.action_name
+        return "#{controller.class.name}##{controller.action_name}"
+      end
+
+      params = env['action_dispatch.request.path_parameters']
+      return nil unless params.is_a?(Hash)
+
+      name = params[:controller] || params['controller']
+      action = params[:action] || params['action']
+      return nil if name.to_s.empty? || action.to_s.empty?
+
+      "#{camelize(name.to_s)}Controller##{action}"
+    rescue StandardError, SystemStackError
+      nil
+    end
+
+    # 'admin/deal_notes' -> 'Admin::DealNotes'. Plain, without
+    # ActiveSupport's inflections, which this gem cannot assume are loaded.
+    def camelize(path)
+      path.split('/').map { |part| part.split('_').map(&:capitalize).join }.join('::')
+    end
+
+    # Tells the browser that something was handled during this request.
+    #
+    # This is the whole of detector 2's server half. The browser already knows
+    # whether the application showed the user an error; it does not know
+    # whether anything went wrong. One header closes that gap, and the join
+    # happens where both facts are present at the same moment — rather than in
+    # a database, which would need per-trace records from both sides and
+    # per-event traffic from the client.
+    #
+    # The value is a count and nothing else. No class name, no message, no
+    # symbol: this header is readable by any script on the page, and the
+    # detail already travels to the sidecar over a unix socket on the
+    # customer's own host.
+    #
+    # CROSS-ORIGIN: a browser cannot read a custom response header unless the
+    # server lists it in Access-Control-Expose-Headers. An Angular app on a
+    # different origin from its Rails API — a common setup — will see
+    # nothing without that. See docs/DETECTORS.md.
+    def mark_handled(result)
+      count = Current.handled_count
+      return result if count.zero?
+
+      status, headers, body = result
+      headers = headers.dup
+      headers[HANDLED_HEADER] = count.to_s
+
+      exposed = headers[EXPOSE_HEADER].to_s
+      unless exposed.downcase.include?(HANDLED_HEADER)
+        headers[EXPOSE_HEADER] = exposed.empty? ? HANDLED_HEADER : "#{exposed}, #{HANDLED_HEADER}"
+      end
+
+      [status, headers, body]
+    rescue StandardError
+      # Never fail a response over instrumentation.
+      result
+    end
+  end
+end

data/lib/devbench/rails_hooks.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require_relative 'reporter'
+
+module Devbench
+  # The Rails-side exception hooks (docs/SERVER_SDK_SPEC.md, Capability 2).
+  #
+  # Plain Ruby: nothing here names a Rails constant, so this file loads
+  # without Rails. Devbench::Railtie installs the hooks against the real
+  # Rails.error and ActiveSupport::Notifications at boot.
+  #
+  # Every entry point here runs inside Rails' own error and instrumentation
+  # paths. Since Rails 7.1 an exception raised by a notification subscriber
+  # is re-raised into the code being instrumented, so a fault in these hooks
+  # would fail the customer's job — every one of them is fully guarded.
+  module RailsHooks
+    JOB_EVENT = 'perform.active_job'
+
+    # Where Rails' executor says it caught an error, mapped to the context a
+    # triager would use. From Rails 7.1, ActionDispatch::Executor reports an
+    # unhandled request exception (raised, or rendered as a 500 by
+    # ShowExceptions) to Rails.error before Devbench::Middleware, outermost, sees
+    # it, so this subscriber is the first hook it reaches. Labelling it
+    # `rails_error` would leave `request` empty on every modern Rails app.
+    #
+    # Jobs need no entry: the perform.active_job hook runs inside the job,
+    # before the executor around it reports.
+    #
+    # Sidekiq's Rails reloader wraps each job in the executor with
+    # source 'job.sidekiq', so a failure outside Sidekiq's middleware (a job
+    # class that will not load) reaches Rails.error first. It is a job
+    # failure.
+    SOURCE_CONTEXTS = {
+      'application.action_dispatch' => 'request',
+      'job.sidekiq' => 'job'
+    }.freeze
+
+    # Subscribed to Rails.error (Rails >= 7.0). Receives both Rails.error
+    # .report and .handle; `handled` is passed through as Rails gives it.
+    class ErrorSubscriber
+      def report(error, handled: false, severity: nil, context: nil, source: nil, **_rest)
+        Reporter.capture(
+          error,
+          context: SOURCE_CONTEXTS.fetch(source.to_s, 'rails_error'),
+          handled: handled,
+          symbol: RailsHooks.symbol_from_context(context)
+        )
+        nil
+      rescue StandardError, SystemStackError
+        nil
+      end
+    end
+
+    class << self
+      # Subscribes once per reporter. Returns true when subscribed.
+      def install_error_reporter(reporter)
+        return false if reporter.nil? || !reporter.respond_to?(:subscribe)
+        return true if error_reporters.any? { |r| r.equal?(reporter) }
+
+        reporter.subscribe(ErrorSubscriber.new)
+        error_reporters << reporter
+        true
+      rescue StandardError, SystemStackError
+        false
+      end
+
+      # Subscribes once per notifier. Returns true when subscribed.
+      def install_active_job(notifications)
+        return false if notifications.nil? || !notifications.respond_to?(:subscribe)
+        return true if job_notifiers.any? { |n| n.equal?(notifications) }
+
+        notifications.subscribe(JOB_EVENT) do |_name, _started, _finished, _id, payload|
+          job_performed(payload)
+        end
+        job_notifiers << notifications
+        true
+      rescue StandardError, SystemStackError
+        false
+      end
+
+      # A perform.active_job payload. ActiveJob puts the exception that
+      # escaped #perform in :exception_object.
+      def job_performed(payload)
+        return nil unless payload.is_a?(Hash)
+
+        error = payload[:exception_object]
+        return nil if error.nil?
+
+        Reporter.capture(error, context: 'job', handled: false, symbol: job_symbol(payload[:job]))
+      rescue StandardError, SystemStackError
+        nil
+      end
+
+      # Rails >= 7.1 puts the controller or job being run into the error
+      # context (ActiveSupport::ExecutionContext).
+      def symbol_from_context(context)
+        return nil unless context.is_a?(Hash)
+
+        controller = context[:controller]
+        if controller.respond_to?(:action_name) && controller.action_name
+          return "#{controller.class.name}##{controller.action_name}"
+        end
+
+        job_symbol(context[:job])
+      rescue StandardError, SystemStackError
+        nil
+      end
+
+      private
+
+      def job_symbol(job)
+        return nil if job.nil?
+
+        "#{job.class.name}#perform"
+      end
+
+      def error_reporters
+        @error_reporters ||= []
+      end
+
+      def job_notifiers
+        @job_notifiers ||= []
+      end
+    end
+  end
+end

data/lib/devbench/railtie.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require_relative 'middleware'
+require_relative 'rails_hooks'
+require_relative 'sidekiq_hooks'
+
+module Devbench
+  # Hooks Dev Bench into Rails at boot. Loaded by lib/devbench.rb only when
+  # Rails::Railtie is defined, so the gem still loads, with zero
+  # dependencies, in plain Ruby.
+  class Railtie < ::Rails::Railtie
+    # Inserts Devbench::Middleware first in the stack, as sentry-rails
+    # inserts its own, so `gem 'devbench'` is the whole install.
+    #
+    # Unless the app already did: every install before 0.5 has
+    # `config.middleware.insert_before 0, ADT::Middleware` in
+    # config/application.rb, and ADT::Middleware is this class. Inserting
+    # again would put it in the stack twice.
+    #
+    # Whether the app inserted it is only knowable once every operation the
+    # app recorded has been replayed onto the real stack — including ones
+    # from config/initializers, which run after this initializer. So the
+    # check is itself recorded as an operation, and in the list Rails
+    # replays last (delete/move operations), where it sees the finished
+    # stack. Rails >= 7.1 records operations as lambdas taking the stack;
+    # 7.0 as [method, args, block] it public_sends, which `then` serves.
+    initializer 'devbench.middleware', before: :build_middleware_stack do |app|
+      Railtie.auto_insert(app.config.middleware)
+    end
+
+    # Puts the request's trace on every Rails log line (SERVER_SDK_SPEC,
+    # Capability 1, requirement 2), so the sidecar can hand triage the server
+    # lines of one user action. Appended to whatever the app already tags
+    # with — e.g. [:request_id] — never replacing it. Before the middleware
+    # stack is built, which is when Rails::Rack::Logger reads log_tags.
+    initializer 'devbench.log_tags', before: :build_middleware_stack do |app|
+      tags = Array(app.config.log_tags)
+      app.config.log_tags = tags + [Devbench::LOG_TAG] unless tags.include?(Devbench::LOG_TAG)
+    rescue StandardError, SystemStackError
+      nil
+    end
+
+    # rake devbench:test — check the DSN without waiting for a flush.
+    rake_tasks do
+      namespace :devbench do
+        desc 'Send one test exception straight to Dev Bench and print the HTTP result'
+        task test: :environment do
+          abort('Dev Bench test failed (see above)') unless Devbench.test!
+        end
+      end
+    end
+
+    config.after_initialize do
+      # A diagnostics gem that can fail a boot is worse than none.
+      begin
+        next unless Devbench.enabled?
+
+        Devbench::RailsHooks.install_error_reporter(::Rails.error) if ::Rails.respond_to?(:error)
+        if defined?(::ActiveSupport::Notifications)
+          Devbench::RailsHooks.install_active_job(::ActiveSupport::Notifications)
+        end
+        # Native Sidekiq jobs never reach the ActiveJob hook. after_initialize
+        # runs after every gem is required, so Gemfile order does not matter.
+        Devbench::SidekiqHooks.install if defined?(::Sidekiq)
+      rescue StandardError, SystemStackError
+        nil
+      end
+    end
+
+    class << self
+      # Records the conditional insert on a MiddlewareStackProxy. Returns
+      # true when recorded.
+      def auto_insert(proxy)
+        operations = proxy.send(:delete_operations)
+        check = ->(stack) { insert_unless_present(stack) }
+        operations << (lambda_operations?(operations) ? check : [:then, [], check])
+        true
+      rescue StandardError, SystemStackError
+        # A Rails whose proxy no longer looks like this: insert plainly. Two
+        # copies (if the app also inserted one) would cost a second scope
+        # per request, never a second report — capture dedupes per object.
+        begin
+          proxy.insert_before(0, Devbench::Middleware)
+        rescue StandardError, SystemStackError
+          nil
+        end
+        false
+      end
+
+      def insert_unless_present(stack)
+        return stack unless Devbench.enabled?
+
+        present = stack.middlewares.any? { |m| m.klass.equal?(Devbench::Middleware) }
+        stack.unshift(Devbench::Middleware) unless present
+        stack
+      end
+
+      private
+
+      def lambda_operations?(operations)
+        return operations.first.is_a?(Proc) unless operations.empty?
+
+        ::Rails.gem_version >= Gem::Version.new('7.1')
+      end
+    end
+  end
+end

data/lib/devbench/reporter.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require_relative 'current'
+require_relative 'backtrace'
+require_relative 'transport'
+
+module Devbench
+  # Turns a failure into a report — the control message of
+  # docs/SERVER_SDK_SPEC.md, "Control socket — v1" — and hands it to the
+  # active transport (Devbench.transport): direct to Dev Bench when a DSN is
+  # set, else the local sidecar's socket.
+  #
+  # The report is built the same way for both, so the direct transport
+  # fingerprints exactly what the sidecar would have received.
+  #
+  # Every failure here is swallowed. This is the one place in the codebase
+  # where that is correct — everywhere else it is the exact behavior the
+  # product exists to find.
+  module Reporter
+    DEFAULT_SOCKET = '/tmp/adt-sidecar.sock'
+
+    # docs/SERVER_SDK_SPEC.md, "Control socket — v1".
+    MAX_MESSAGE = 2000
+    MAX_HANDLED_MESSAGE = 500
+
+    CONTEXTS = %w[request rails_error job explicit].freeze
+
+    # Status codes, not failures. Matched by name against the exception's
+    # class and ancestors, so none of these constants needs to be loaded —
+    # this gem must work without Rails. Sentry ignores the same by default.
+    DEFAULT_IGNORED = %w[
+      ActionController::RoutingError
+      ActiveRecord::RecordNotFound
+      ActionController::InvalidAuthenticityToken
+      ActionController::UnknownFormat
+      ActionDispatch::Http::MimeNegotiation::InvalidType
+    ].freeze
+
+    # Process control, not application failures: a deploy's SIGTERM or an
+    # `exit` passing through the middleware is not something to triage.
+    #
+    # Sidekiq's own control flow likewise (Sidekiq::Shutdown is an Interrupt,
+    # so already a SignalException). JobRetry::Handled (and its subclass
+    # Skip) means "the job failed and Sidekiq has dealt with it" — the real
+    # failure is its cause, reported on its own; Rails' executor around a
+    # Sidekiq job would otherwise hand it to Rails.error. Job::Interrupted is
+    # an iterable job being re-queued at shutdown.
+    NEVER_REPORTED = %w[
+      SystemExit SignalException
+      Sidekiq::JobRetry::Handled Sidekiq::Job::Interrupted
+    ].freeze
+
+    REPORTED_IVAR = :@__adt_reported
+
+    class << self
+      attr_writer :socket_path, :app_root
+
+      def socket_path
+        @socket_path ||= ENV.fetch('ADT_SIDECAR_SOCKET', DEFAULT_SOCKET)
+      end
+
+      # Class names never reported. Extend it from an initializer:
+      #
+      #   Devbench.ignore_exceptions << 'Pundit::NotAuthorizedError'
+      def ignore_exceptions
+        @ignore_exceptions ||= DEFAULT_IGNORED.dup
+      end
+
+      # Frames under this directory are sent relative to it. Rails.root when
+      # Rails is loaded, else the working directory.
+      def app_root
+        return @app_root if @app_root
+
+        if defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root
+          ::Rails.root.to_s
+        else
+          Dir.pwd
+        end
+      rescue StandardError, SystemStackError
+        nil
+      end
+
+      # Records that a failure was handled here. Does not change behavior.
+      #
+      #   rescue ActiveRecord::RecordInvalid => e
+      #     Devbench.report_handled(e, symbol: 'CustomersController#update', reason: 'validation')
+      def report_handled(error, symbol:, reason: nil)
+        # Counted first, and regardless of whether anything after it works.
+        # The count is what the browser is told; a sidecar that is down, or an
+        # error object that misbehaves, must not also make the failure
+        # invisible to the detector that does not need either.
+        begin
+          Current.record_handled
+        rescue StandardError, SystemStackError
+          nil
+        end
+
+        emit(handled_payload(error, symbol, reason))
+        nil
+      rescue StandardError, SystemStackError
+        # This runs inside the customer's rescue blocks. Anything raised here
+        # means their render never runs — a handled failure turned into an
+        # outage by the tool watching for failures.
+        nil
+      end
+
+      # Sends an `exception` message, once per exception object.
+      #
+      # Called from the middleware's rescue, from Rails.error, from ActiveJob
+      # instrumentation and from Devbench.capture_exception. Anything raised here
+      # would replace the application's own exception, so nothing is.
+      def capture(error, context:, handled:, symbol: nil)
+        return nil unless error.is_a?(Exception)
+        return nil if reported?(error) || ignored?(error)
+
+        # Marked before sending, so a second hook reached while this one is
+        # still writing does not send it again.
+        mark_reported(error)
+        emit(exception_payload(error, context, handled, symbol))
+        nil
+      rescue StandardError, SystemStackError
+        nil
+      end
+
+      # Whether an exception has already been sent by any hook.
+      def reported?(error)
+        if error.instance_variable_defined?(REPORTED_IVAR)
+          true
+        else
+          frozen_reported.key?(error)
+        end
+      rescue StandardError, SystemStackError
+        false
+      end
+
+      def ignored?(error)
+        names = error.class.ancestors.map(&:name)
+        return true if (names & NEVER_REPORTED).any?
+
+        (names & ignore_exceptions.map(&:to_s)).any?
+      rescue StandardError, SystemStackError
+        false
+      end
+
+      # The `exception` report for an error, without sending it. Used by
+      # the self-test (Devbench.test!), which sends one synthetic report
+      # straight to ingest, built exactly as a real one would be.
+      def report_for(error, context:, handled:, symbol: nil)
+        exception_payload(error, context, handled, symbol)
+      end
+
+      private
+
+      def mark_reported(error)
+        error.instance_variable_set(REPORTED_IVAR, true)
+      rescue FrozenError
+        # A frozen exception cannot carry the mark. Held weakly, so the
+        # process does not keep every frozen exception it ever saw.
+        frozen_reported[error] = true
+      end
+
+      def frozen_reported
+        @frozen_reported ||= ObjectSpace::WeakMap.new
+      end
+
+      # Hands the report to whichever transport is active: direct (DSN set),
+      # the sidecar socket, or none. Each one returns at once and swallows its
+      # own failures; this guard is for the dispatch itself.
+      def emit(payload)
+        Devbench.transport.deliver(payload)
+      rescue StandardError, SystemStackError
+        nil
+      end
+
+      # Each field is read on its own: an exception whose #message raises
+      # still reports its class and site, which are the fingerprint. The
+      # message is detail.
+      def handled_payload(error, symbol, reason)
+        {
+          v: 1,
+          kind: 'handled_failure',
+          symbol: symbol,
+          error: safely { error.class.name },
+          message: safely { truncate(error.message, MAX_HANDLED_MESSAGE) },
+          reason: reason,
+          trace: safely { Current.trace&.to_s },
+          user: safely { Current.user }
+        }.compact
+      end
+
+      def exception_payload(error, context, handled, symbol)
+        {
+          v: 1,
+          kind: 'exception',
+          context: CONTEXTS.include?(context) ? context : 'explicit',
+          handled: handled ? true : false,
+          error: safely { class_name(error) } || 'Exception',
+          message: safely { truncate(error.message, MAX_MESSAGE) },
+          symbol: safely { symbol.nil? ? nil : utf8(symbol.to_s) } || '',
+          frames: safely { Backtrace.frames(error.backtrace, app_root) } || [],
+          trace: safely { Current.trace&.to_s },
+          user: safely { Current.user }
+        }.compact
+      end
+
+      # An anonymous class has no name; its nearest named ancestor is stable
+      # across processes, where Class#to_s would print an address.
+      def class_name(error)
+        error.class.ancestors.find { |mod| mod.is_a?(Class) && mod.name }&.name
+      end
+
+      def safely
+        yield
+      rescue StandardError, SystemStackError
+        nil
+      end
+
+      # At most `limit` characters, including the ellipsis.
+      def truncate(text, limit)
+        text = utf8(text.to_s)
+        text.length > limit ? "#{text[0, limit - 1]}…" : text
+      end
+
+      def utf8(text)
+        text.encode('UTF-8', invalid: :replace, undef: :replace).scrub
+      end
+    end
+  end
+
+  # Reports an exception the application caught and wants seen, as Sentry's
+  # capture_exception does. Returns nil and never raises.
+  #
+  #   rescue Faraday::Error => e
+  #     Devbench.capture_exception(e, symbol: 'Billing::Sync#run')
+  def self.capture_exception(error, symbol: nil)
+    Reporter.capture(error, context: 'explicit', handled: true, symbol: symbol)
+  end
+
+  def self.report_handled(error, symbol:, reason: nil)
+    Reporter.report_handled(error, symbol: symbol, reason: reason)
+  end
+
+  # Class names never reported as exceptions (see Reporter::DEFAULT_IGNORED).
+  def self.ignore_exceptions
+    Reporter.ignore_exceptions
+  end
+end