devbench 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: be38d75135b0a120747e5abf3889afadb0997377f8d58510abb5a3baadf41d64
+  data.tar.gz: d2791c38e21e79d204e71a22aa3337793b9641976827aeb0f5e6dd54a7f811dc
+SHA512:
+  metadata.gz: 3f323a0cd9aa89ed80cee8fa78c8598c992f8ac15200bc7bf98ee5cc211079dc1458237c782479c150643a944683b27fe3b295222d1f7b2e8ec5a3bf0bacab5c
+  data.tar.gz: ec896fbc0a0d4d65d6259a83186f81df942cc09d0f437995cc34f80a4ab66c0864b90c948b944054c8404fa1f16047b002f7f5d2c56f84a9500dbaf304bc4d25

data/README.md

@@ -0,0 +1,225 @@
+# Dev Bench for Ruby and Rails
+
+Everything Sentry's Rails SDK captures by default, plus who was affected,
+trace propagation and the handled-failure header — so an app can turn
+Sentry off. Zero runtime dependencies; loads in plain Ruby, hooks itself
+into Rails when Rails is there.
+
+## Install (Rails)
+
+```ruby
+# Gemfile
+gem 'devbench'
+```
+
+```sh
+# The DSN Dev Bench gave you for this environment
+DEVBENCH_DSN=https://<key>@adt-ingest.onrender.com
+```
+
+That is the whole install. No middleware line, no initializer, no process
+to run next to the app. Check it:
+
+```sh
+bin/rails devbench:test
+# Dev Bench: sending a test exception to https://adt-ingest.onrender.com (service "acme_shop")
+#   HTTP 200: accepted (fingerprint 3f9a2b0c4d5e)
+```
+
+It prints the HTTP result, or says plainly what is wrong (`DEVBENCH_DSN is
+not set`, `HTTP 401: the key in DEVBENCH_DSN was rejected`, `could not reach
+…`) and exits non-zero. Outside Rake: `Devbench.test!`.
+
+## Configuration
+
+All optional except the DSN.
+
+| Variable | Default | |
+|---|---|---|
+| `DEVBENCH_DSN` | — (falls back to `ADT_DSN`) | `https://<key>@<host>[:port]`. Plain `http://` is accepted only for localhost. |
+| `DEVBENCH_SERVICE` | your app's module, underscored (`AcmeShop` → `acme_shop`); `app` outside Rails | Groups this app's issues. |
+| `DEVBENCH_RELEASE` | `GIT_SHA`, `SOURCE_VERSION`, `RENDER_GIT_COMMIT`, else empty | Which deploy an occurrence came from. |
+| `DEVBENCH_ENABLED` | on | `false` turns everything off: no middleware, no hooks, nothing sent. |
+
+Or from code, e.g. `config/initializers/devbench.rb`:
+
+```ruby
+Devbench.configure do |c|
+  c.dsn = Rails.application.credentials.devbench_dsn
+  c.service = 'billing-api'
+end
+```
+
+A DSN that does not parse logs one `[devbench]` warning and reports
+nothing; it never raises into the app.
+
+## What is captured automatically
+
+| What | How | `context` |
+|---|---|---|
+| An exception escaping the app | `Devbench::Middleware` (inserted first in the stack by the Railtie) reports it, then re-raises the same object, backtrace intact | `request` |
+| An exception Rails rendered as a 500 page itself | `Devbench::Middleware` (`env['action_dispatch.exception']`), or `Rails.error` from Rails 7.1's executor | `request` |
+| `Rails.error.report` / `Rails.error.handle` (Rails ≥ 7.0) | the Railtie subscribes; `handled` is passed through | `rails_error` |
+| A failed ActiveJob | the Railtie subscribes to `perform.active_job` | `job` |
+| A failed Sidekiq job (`Sidekiq::Job` / `Sidekiq::Worker`) | Sidekiq server middleware; reports, then re-raises the same object, so retries are unchanged | `job` |
+| A Sidekiq error outside a job (Redis/fetch errors, a death handler that raised) | Sidekiq `error_handlers` | `job` |
+
+Each report carries the class, the message (≤ 2,000 characters), where it
+surfaced (`DealsController#update`, `InvoiceJob#perform`), up to 50 stack
+frames with paths relative to `Rails.root`, the trace, and the user.
+
+- **Once per exception.** An error that passes several hooks (a job failing
+  inside a request reaches three) is reported once.
+- **Status codes are not failures.** Not reported, as in Sentry:
+  `ActionController::RoutingError`, `ActiveRecord::RecordNotFound`,
+  `ActionController::InvalidAuthenticityToken`,
+  `ActionController::UnknownFormat`,
+  `ActionDispatch::Http::MimeNegotiation::InvalidType`, and subclasses. Add
+  your own by name:
+
+  ```ruby
+  Devbench.ignore_exceptions << 'Pundit::NotAuthorizedError'
+  ```
+
+- **Never in the way.** No hook raises into the app; a failure while
+  reporting is dropped, and the application's own exception always comes
+  out unchanged.
+
+## What is sent, and when
+
+Like the browser sensor, the gem does not send one request per error:
+
+- Each report is **fingerprinted and counted in the process** (class,
+  templated message and in-app frames; the same algorithm as every other
+  Dev Bench sensor). Repeats cost a counter increment.
+- **Once a minute** a background thread sends the counts — fingerprint,
+  how many, first/last seen, and up to 20 affected users each — in one
+  small request. Nothing is sent for a quiet minute, and what is left is
+  sent when the process exits (waiting at most 2 seconds).
+- **Detail only on request.** When Dev Bench sees a fingerprint for the
+  first time it asks for evidence, and the gem uploads the stack and one
+  example message — **templated and scrubbed first** (emails, numbers,
+  quoted values, tokens, card numbers, credentials and two-word names are
+  removed). Who was affected never goes into evidence.
+- **Never harms the app.** No network I/O on the request thread; 5-second
+  timeouts on the background thread, one retry, then the data is dropped;
+  memory is bounded (512 distinct problems per minute, the rest only
+  counted). Safe under forking servers (Puma, Unicorn, Sidekiq): each
+  worker reports on its own.
+
+## Who was affected
+
+Set it once per request, typically in `ApplicationController`:
+
+```ruby
+before_action do
+  Devbench.set_user(email: current_user&.email, account: current_account&.id)
+end
+```
+
+- `email` is trimmed and lowercased; `account` is your own tenant/customer
+  id, sent as a string. Both optional, each truncated to 255 characters.
+- It is sent in its own field with the counts, never inside a message or
+  evidence, and triage sees counts of affected users and accounts.
+- The middleware clears it when the request ends (Sidekiq: when the job
+  ends), so the next request on the same thread never inherits it.
+
+## Reporting what you caught
+
+An exception you rescued but want seen, like Sentry's `capture_exception`:
+
+```ruby
+rescue Faraday::Error => e
+  Devbench.capture_exception(e, symbol: 'Billing::Sync#run')
+  retry_later
+end
+```
+
+A failure you handled and turned into a normal response — the case this
+product exists for:
+
+```ruby
+rescue ActiveRecord::RecordInvalid => e
+  Devbench.report_handled(e, symbol: 'CustomersController#update', reason: 'validation')
+  render json: { ok: true }   # <- the user is about to be told this worked
+end
+```
+
+`report_handled` also marks the response with `x-adt-handled: <count>`. The
+browser already knows whether the user was shown an error; this is the one
+fact it cannot know on its own. The header carries a count and nothing else,
+and it is added even when reporting is down.
+
+## Sidekiq
+
+Under Rails there is nothing to add: the Railtie installs the hooks at boot
+when Sidekiq is loaded. A Sidekiq process **without Rails** installs them
+itself, wherever it configures Sidekiq:
+
+```ruby
+require 'sidekiq'
+require 'devbench'
+Devbench::SidekiqHooks.install
+```
+
+That adds a server middleware (first in the chain; reports, then re-raises,
+so retries and the dead set are unchanged), identity scoped to each job, the
+request's trace carried into jobs it enqueues (`"adt_trace"` in the job
+payload), and an error handler for failures outside a job. Sidekiq's own
+control flow (`Sidekiq::Shutdown`, `JobRetry::Handled`/`Skip`,
+`Job::Interrupted`) is never reported. Tested against Sidekiq 7.3; not a
+dependency of this gem.
+
+## Without Rails
+
+```ruby
+require 'devbench'
+use Devbench::Middleware   # Rack
+```
+
+Everything else (`set_user`, `capture_exception`, `report_handled`, the
+DSN) works the same.
+
+## Trace propagation
+
+The correlation id the browser sent (`x-adt-trace`) is available as
+`Devbench::Current.trace` for the duration of the request. Forward it on
+outbound calls to other instrumented services:
+
+```ruby
+Net::HTTP.post(uri, body, Devbench::HTTP.headers)
+```
+
+## Cross-origin
+
+If your JavaScript is served from a different origin than this API, the
+browser cannot read `x-adt-handled` unless the server lists it in
+`Access-Control-Expose-Headers`. The middleware adds it and appends rather
+than overwrites. **A CORS layer that replaces the response header set will
+strip it** and detection will silently never fire; check the ordering.
+
+## Optional: the sidecar (server logs)
+
+The Dev Bench sidecar is a separate process that reads your app's log
+stream on the host and answers triage's requests for the log lines of one
+user action. It is optional; nothing above needs it.
+
+Without a DSN, the gem reports to the sidecar's unix socket instead
+(`$ADT_SIDECAR_SOCKET`, default `/tmp/adt-sidecar.sock`), exactly as 0.4
+did, and the sidecar counts and uploads on its behalf. **It never uses
+both**: with a DSN set, a sidecar on the same host still reads logs, but the
+gem does not also write to its socket, so nothing is counted twice.
+Fingerprints are identical in both modes, so moving between them keeps
+every issue.
+
+## Upgrading from `adt` (0.4)
+
+- Change the Gemfile line to `gem 'devbench'`. `require 'adt'` and every
+  `ADT.set_user`, `ADT.report_handled`, `ADT.capture_exception`,
+  `ADT::Middleware` and `ADT::SidekiqHooks` keep working unchanged: `ADT`
+  is `Devbench`.
+- `config.middleware.insert_before 0, ADT::Middleware` can stay or go: the
+  Railtie sees it and does not insert a second one.
+- Running the sidecar and want to keep it that way? Change nothing else.
+  To report directly instead, set `DEVBENCH_DSN` (a key minted with
+  `--source server`); the sidecar then only serves logs.

data/lib/adt.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# The pre-0.5 entry point. Installs that `require 'adt'` keep working
+# unchanged: ADT is Devbench.
+require_relative 'devbench'

data/lib/devbench/backtrace.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Devbench
+  # Turns Ruby backtrace lines into the control socket's frames:
+  # [{function:, file:, line:}], innermost first.
+  #
+  # Ruby has changed this format under us before. Up to 3.3:
+  #
+  #   /app/models/deal.rb:42:in `block in save'
+  #
+  # From 3.4, a straight quote, and the label carries the owner:
+  #
+  #   /app/models/deal.rb:42:in 'block in Deal#save'
+  #
+  # Both parse to the same file and line; the function is whatever Ruby said.
+  module Backtrace
+    MAX_FRAMES = 50
+    # Bounds one frame so 50 of them cannot push a message past the socket's
+    # 256 KiB line limit.
+    MAX_FIELD = 1024
+    LINE = /\A(.+?):(\d+)(?::in [`'](.*)')?\z/m
+
+    def self.frames(backtrace, root)
+      return [] unless backtrace.is_a?(Array)
+
+      prefix = root_prefix(root)
+      backtrace.first(MAX_FRAMES).map { |raw| frame(utf8(raw.to_s), prefix) }
+    end
+
+    def self.frame(raw, prefix)
+      match = LINE.match(raw)
+      # Unparseable lines are kept whole rather than dropped: a frame the
+      # parser did not understand is still evidence.
+      return { function: '', file: clip(raw), line: 0 } if match.nil?
+
+      file = match[1]
+      file = file[prefix.length..] if prefix && file.start_with?(prefix)
+
+      { function: clip(match[3].to_s), file: clip(file), line: match[2].to_i }
+    end
+
+    def self.root_prefix(root)
+      root = root.to_s
+      return nil if root.empty?
+
+      root.end_with?('/') ? root : "#{root}/"
+    end
+
+    def self.clip(text)
+      text.length > MAX_FIELD ? text[0, MAX_FIELD] : text
+    end
+
+    # JSON.generate raises on invalid UTF-8, which would lose the whole report
+    # over one byte in a path.
+    def self.utf8(text)
+      text.encode('UTF-8', invalid: :replace, undef: :replace).scrub
+    end
+
+    private_class_method :frame, :root_prefix, :clip, :utf8
+  end
+end

data/lib/devbench/config.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module Devbench
+  # Where reports go, parsed from DEVBENCH_DSN (docs/SERVER_SDK_SPEC.md, "Dev
+  # Bench naming and configuration"):
+  #
+  #   https://<ingest key>@<host>[:port]
+  #
+  # scheme://host[:port] is the ingest base and the userinfo is the key. A
+  # path or query, if present, is ignored: the key alone identifies tenant,
+  # environment and source.
+  class DSN
+    class Invalid < StandardError; end
+
+    LOOPBACK = /\A(?:localhost|127(?:\.\d{1,3}){3}|::1|\[::1\])\z|\.localhost\z/i
+
+    attr_reader :base, :key
+
+    def initialize(base, key)
+      @base = base.freeze
+      @key = key.freeze
+      freeze
+    end
+
+    def flush_url
+      "#{@base}/v1/flush"
+    end
+
+    # The DSN without its key, for messages and logs. The key is a secret
+    # on a server: it must never be printed.
+    def to_s
+      @base
+    end
+
+    alias inspect to_s
+
+    # Raises DSN::Invalid with a message that says what to fix. Never echoes
+    # the key back.
+    def self.parse(raw)
+      text = raw.to_s.strip
+      raise Invalid, 'is empty' if text.empty?
+
+      uri = begin
+        URI.parse(text)
+      rescue URI::Error
+        raise Invalid, 'is not a URL (expected https://<key>@<host>)'
+      end
+
+      scheme = uri.scheme.to_s.downcase
+      raise Invalid, 'must start with https:// (expected https://<key>@<host>)' unless %w[http https].include?(scheme)
+
+      host = uri.host.to_s
+      raise Invalid, 'has no host (expected https://<key>@<host>)' if host.empty?
+
+      key = URI.decode_www_form_component(uri.user.to_s)
+      raise Invalid, 'has no key (expected https://<key>@<host>)' if key.strip.empty?
+
+      # The key is a real secret on a server. Over plain http it would cross
+      # the network readable by anything on the path, so http is accepted
+      # only for a loopback ingest (local development and tests).
+      if scheme == 'http' && !LOOPBACK.match?(host)
+        raise Invalid, "uses http:// for #{host}: the key would cross the network in plaintext; use https://"
+      end
+
+      port = uri.port && uri.port != uri.default_port ? ":#{uri.port}" : ''
+      host = "[#{host}]" if host.include?(':') && !host.start_with?('[')
+      new("#{scheme}://#{host}#{port}", key.strip)
+    end
+  end
+
+  # Everything Dev Bench reads at start. From the environment by default;
+  # Devbench.configure sets the same fields from code.
+  #
+  #   DEVBENCH_DSN       where to send (fallback ADT_DSN). Unset: the local
+  #                      sidecar's socket, as before 0.5.
+  #   DEVBENCH_SERVICE   this app's name. Default: the Rails application's
+  #                      module, underscored (AcmeShop -> acme_shop);
+  #                      else "app".
+  #   DEVBENCH_RELEASE   the deployed version. Default: GIT_SHA,
+  #                      SOURCE_VERSION, RENDER_GIT_COMMIT, else "".
+  #   DEVBENCH_ENABLED   "false" turns everything off.
+  class Configuration
+    RELEASE_FALLBACKS = %w[GIT_SHA SOURCE_VERSION RENDER_GIT_COMMIT].freeze
+    OFF = %w[false 0 no off].freeze
+
+    # Strings, or nil for "not set".
+    attr_accessor :dsn, :service, :release
+    # Seconds between background flushes in direct mode (spec: 60).
+    attr_accessor :flush_interval
+    attr_writer :enabled
+
+    def initialize(env = ENV)
+      @dsn = presence(env['DEVBENCH_DSN']) || presence(env['ADT_DSN'])
+      @service = presence(env['DEVBENCH_SERVICE'])
+      @release = presence(env['DEVBENCH_RELEASE']) ||
+                 RELEASE_FALLBACKS.lazy.map { |name| presence(env[name]) }.find(&:itself)
+      @enabled = !OFF.include?(env['DEVBENCH_ENABLED'].to_s.strip.downcase)
+      @flush_interval = 60
+    end
+
+    def enabled?
+      @enabled ? true : false
+    end
+
+    # The service name sent with every flush and folded into every
+    # fingerprint. Resolved when reporting starts, after Rails has booted.
+    def resolved_service
+      presence(@service) || rails_service || 'app'
+    end
+
+    def resolved_release
+      @release.to_s
+    end
+
+    private
+
+    def presence(value)
+      text = value.to_s.strip
+      text.empty? ? nil : text
+    end
+
+    # Rails.application.class.module_parent_name.underscore, without
+    # assuming ActiveSupport's inflections are loaded.
+    def rails_service
+      return nil unless defined?(::Rails) && ::Rails.respond_to?(:application) && ::Rails.application
+
+      klass = ::Rails.application.class
+      name = klass.respond_to?(:module_parent_name) ? klass.module_parent_name : klass.name.to_s.split('::').first
+      return nil if name.nil? || name.empty? || name == 'Object'
+
+      name.respond_to?(:underscore) ? name.underscore : underscore(name)
+    rescue StandardError, SystemStackError
+      nil
+    end
+
+    def underscore(name)
+      name.gsub('::', '/')
+          .gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .tr('-', '_')
+          .downcase
+    end
+  end
+end

data/lib/devbench/current.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Devbench
+  # Per-request storage for the active trace.
+  #
+  # Plain thread/fiber-local rather than ActiveSupport::CurrentAttributes, so
+  # the core of this gem loads and is testable without Rails. The Railtie wires
+  # CurrentAttributes semantics where Rails is present.
+  module Current
+    KEY = :__adt_trace
+    HANDLED_KEY = :__adt_handled
+    USER_KEY = :__adt_user
+
+    # Counts failures handled during this request.
+    #
+    # The middleware turns a non-zero count into a response header, which is
+    # what lets the browser decide — at the moment it has both facts — whether
+    # the user was told. See docs/DETECTORS.md.
+    def self.handled_count
+      Thread.current[HANDLED_KEY] || 0
+    end
+
+    def self.record_handled
+      Thread.current[HANDLED_KEY] = handled_count + 1
+    end
+
+    # Who this request is for, as set by Devbench.set_user: a frozen hash with
+    # :email and/or :account, or nil. Normalised before it gets here.
+    def self.user
+      Thread.current[USER_KEY]
+    end
+
+    def self.user=(value)
+      Thread.current[USER_KEY] = value
+    end
+
+    def self.trace
+      Thread.current[KEY]
+    end
+
+    def self.trace=(value)
+      Thread.current[KEY] = value
+    end
+
+    # Runs the block with trace active, restoring whatever was there before.
+    #
+    # Restores rather than clearing, because servers reuse threads: clearing
+    # would leak one request's absence into the next request's presence.
+    def self.with(trace)
+      previous = Thread.current[KEY]
+      previous_handled = Thread.current[HANDLED_KEY]
+      previous_user = Thread.current[USER_KEY]
+      Thread.current[KEY] = trace
+      # Reset rather than inherit: servers reuse threads, and carrying a count
+      # across requests would mark an innocent response as having swallowed
+      # the previous request's failure.
+      Thread.current[HANDLED_KEY] = 0
+      # Same for identity, and more so: inheriting it would attribute one
+      # user's failure to whoever this thread served before.
+      Thread.current[USER_KEY] = nil
+      yield
+    ensure
+      Thread.current[KEY] = previous
+      Thread.current[HANDLED_KEY] = previous_handled
+      Thread.current[USER_KEY] = previous_user
+    end
+
+    def self.clear
+      Thread.current[KEY] = nil
+      Thread.current[HANDLED_KEY] = nil
+      Thread.current[USER_KEY] = nil
+    end
+  end
+end