devbench 0.5.0

data/lib/devbench/trace.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Devbench
+  # The correlation id that ties a user action together across every service.
+  #
+  # Wire form (docs/SERVER_SDK_SPEC.md): v1/<session>/<intent>/<hop>
+  #
+  # This must agree exactly with the Go SDK and the sidecar's extraction regex.
+  # A trace the browser writes and Rails mangles is worse than no trace: the
+  # request still succeeds, so nothing looks wrong, and the evidence simply
+  # cannot be joined.
+  class Trace
+    HEADER = 'x-adt-trace'
+    RACK_HEADER = 'HTTP_X_ADT_TRACE'
+    MAX_HOP = 99
+    ID = /\A[A-Za-z0-9_-]{1,64}\z/
+
+    attr_reader :session, :intent, :hop
+
+    def initialize(session, intent, hop)
+      @session = session
+      @intent = intent
+      @hop = hop
+    end
+
+    # Parses a header value. Returns nil rather than raising: ADT must never
+    # fail a customer's request, and a request carrying a mangled correlation
+    # id is still a request the user wants served.
+    def self.parse(value)
+      return nil unless value.is_a?(String)
+
+      value = value.strip
+      return nil unless value.start_with?('v1/')
+
+      parts = value[3..].split('/', -1)
+      return nil unless parts.length == 3
+
+      session, intent, hop = parts
+      return nil unless session =~ ID && intent =~ ID
+      return nil unless hop =~ /\A\d{1,3}\z/
+
+      hop = hop.to_i
+      return nil if hop.negative? || hop > MAX_HOP
+
+      new(session, intent, hop)
+    end
+
+    def to_s
+      "v1/#{@session}/#{@intent}/#{@hop}"
+    end
+
+    # Identifies the user action, independent of which service saw it.
+    def key
+      "#{@session}/#{@intent}"
+    end
+
+    # The trace to send to a downstream service.
+    def next_hop
+      return nil if @hop >= MAX_HOP
+
+      Trace.new(@session, @intent, @hop + 1)
+    end
+
+    def ==(other)
+      other.is_a?(Trace) && other.session == @session && other.intent == @intent && other.hop == @hop
+    end
+  end
+
+  # A Rails log tag (config.log_tags) carrying the request's x-adt-trace, or
+  # nothing when there is none — Rails drops blank tags. The Railtie adds it;
+  # apps without Rails::Railtie can add it themselves. Never raises: a log
+  # tag that fails takes every log line of the request with it.
+  LOG_TAG = lambda do |request|
+    raw = request.respond_to?(:get_header) ? request.get_header(Trace::RACK_HEADER) : nil
+    Devbench::Trace.parse(raw)&.to_s
+  rescue StandardError, SystemStackError
+    nil
+  end
+end

data/lib/devbench/transport.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require_relative 'config'
+require_relative 'sidecar_transport'
+require_relative 'direct'
+
+# Configuration and transport selection (docs/SERVER_SDK_SPEC.md,
+# "Transports: direct (default) or sidecar (optional)").
+#
+# Exactly one transport per process, decided at the first report:
+#
+#   DEVBENCH_ENABLED=false     -> none
+#   DEVBENCH_DSN (or ADT_DSN)  -> direct to Dev Bench; a DSN that does not
+#                                 parse logs one warning and reports nothing
+#   neither                    -> the sidecar socket, as before 0.5
+#
+# Never both: a sidecar on the same host still reads logs, but writing to
+# its socket as well would count every report twice.
+module Devbench
+  # Raised (and rescued) by Devbench.test! to make its synthetic report.
+  class TestException < StandardError; end
+
+  TRANSPORT_LOCK = Mutex.new
+  CONFIG_LOCK = Mutex.new
+  private_constant :TRANSPORT_LOCK, :CONFIG_LOCK
+
+  class << self
+    # The configuration, read from the environment on first use.
+    def config
+      @config || CONFIG_LOCK.synchronize { @config ||= Configuration.new }
+    end
+
+    # Configures from code instead of (or on top of) the environment, e.g.
+    # in config/initializers/devbench.rb:
+    #
+    #   Devbench.configure do |c|
+    #     c.dsn = Rails.application.credentials.devbench_dsn
+    #     c.service = 'billing'
+    #   end
+    #
+    # Takes effect from the next report. Never raises into the caller.
+    def configure
+      yield config if block_given?
+      reset_transport!
+      nil
+    rescue StandardError, SystemStackError => e
+      warn_once(:configure, "Devbench.configure raised #{e.class}; reporting is unchanged")
+      nil
+    end
+
+    def enabled?
+      config.enabled?
+    rescue StandardError, SystemStackError
+      false
+    end
+
+    # The active transport. Built once, on first use, so a DSN set from an
+    # initializer is seen.
+    def transport
+      @transport || TRANSPORT_LOCK.synchronize { @transport ||= build_transport }
+    end
+
+    # Sends whatever direct mode has counted, now, waiting at most `timeout`
+    # seconds. A no-op in sidecar mode. Returns true when nothing is left
+    # unsent. Never raises.
+    def flush!(timeout: 5)
+      transport.flush!(timeout: timeout) ? true : false
+    rescue StandardError, SystemStackError
+      false
+    end
+
+    # Sends one synthetic exception straight to Dev Bench and prints the
+    # result, so an operator can check the DSN without waiting for a flush
+    # (`rake devbench:test` under Rails). Returns true when ingest accepted
+    # it. Never raises.
+    def test!(io: $stdout)
+      cfg = config
+      unless cfg.enabled?
+        io.puts 'Dev Bench is disabled (DEVBENCH_ENABLED=false); nothing was sent.'
+        return false
+      end
+      if cfg.dsn.nil? || cfg.dsn.strip.empty?
+        io.puts 'DEVBENCH_DSN is not set. Set it to the DSN Dev Bench gave you for this ' \
+                'environment (https://<key>@<host>), or call Devbench.configure { |c| c.dsn = ... }.'
+        return false
+      end
+
+      dsn = begin
+        DSN.parse(cfg.dsn)
+      rescue DSN::Invalid => e
+        io.puts "DEVBENCH_DSN #{e.message}."
+        return false
+      end
+
+      error = begin
+        raise TestException, 'Dev Bench test exception: if you can read this, the DSN works'
+      rescue TestException => e
+        e
+      end
+      payload = Reporter.report_for(error, context: 'explicit', handled: true, symbol: 'devbench:test')
+      client = DirectTransport.new(dsn: dsn, service: cfg.resolved_service, release: cfg.resolved_release)
+      client.self_test(payload, io)
+    rescue StandardError, SystemStackError => e
+      io.puts "Dev Bench test failed: #{e.class}: #{e.message}"
+      false
+    end
+
+    # Drops the active transport (stopping a direct client's thread) and the
+    # configuration, so both are rebuilt from scratch. For tests and for
+    # Devbench.configure.
+    def reset!
+      reset_transport!
+      CONFIG_LOCK.synchronize { @config = nil }
+      nil
+    end
+
+    # Logs a problem with Dev Bench itself, once per kind per process. Never
+    # raises: the logger is the application's.
+    def warn_once(kind, message)
+      @warned ||= {}
+      return if @warned[kind]
+
+      @warned[kind] = true
+      line = "[devbench] #{message}"
+      if defined?(::Rails) && ::Rails.respond_to?(:logger) && ::Rails.logger
+        ::Rails.logger.warn(line)
+      else
+        Kernel.warn(line)
+      end
+      nil
+    rescue StandardError, SystemStackError
+      nil
+    end
+
+    private
+
+    def reset_transport!
+      old = TRANSPORT_LOCK.synchronize do
+        previous = @transport
+        @transport = nil
+        previous
+      end
+      old.stop if old.respond_to?(:stop)
+    end
+
+    def build_transport
+      cfg = config
+      return NullTransport unless cfg.enabled?
+      return SidecarTransport if cfg.dsn.nil? || cfg.dsn.strip.empty?
+
+      dsn = begin
+        DSN.parse(cfg.dsn)
+      rescue DSN::Invalid => e
+        warn_once(:dsn, "DEVBENCH_DSN #{e.message}; nothing will be reported")
+        return NullTransport
+      end
+
+      install_exit_flush
+      DirectTransport.new(dsn: dsn, service: cfg.resolved_service, release: cfg.resolved_release,
+                          interval: cfg.flush_interval)
+    rescue StandardError, SystemStackError
+      NullTransport
+    end
+
+    # One last flush when the process exits, bounded to 2 s (spec). Inherited
+    # by forked children, where it flushes the child's own counts. Not
+    # destructive: a later report (e.g. from a test runner's at_exit) still
+    # works.
+    def install_exit_flush
+      return if @exit_flush_installed
+
+      @exit_flush_installed = true
+      at_exit do
+        current = @transport
+        current.flush!(timeout: DirectTransport::EXIT_TIMEOUT) if current.is_a?(DirectTransport)
+      rescue StandardError, SystemStackError
+        nil
+      end
+    end
+  end
+end

data/lib/devbench/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Devbench
+  # Tracks the protocol, not the gem's own churn.
+  #
+  # The wire format this speaks — the trace header, the handled header, the
+  # control-socket message shapes — is what a customer's deployment depends
+  # on. See docs/SERVER_SDK_SPEC.md.
+  VERSION = '0.5.0'
+end

data/lib/devbench.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Dev Bench server SDK for Ruby/Rails (formerly "ADT"; DECISIONS #160).
+#
+#   gem 'devbench'          # Gemfile
+#   DEVBENCH_DSN=https://<key>@<ingest host>
+#
+# What it does:
+#   * accepts and forwards the correlation id  (Devbench::Middleware, Devbench::HTTP)
+#   * reports handled failures                 (Devbench.report_handled)
+#   * records who was affected                 (Devbench.set_user)
+#   * reports unhandled exceptions             (Devbench::Middleware, Devbench::Railtie,
+#                                               Devbench::SidekiqHooks,
+#                                               Devbench.capture_exception)
+#
+# The old name is kept: `require 'adt'` and every `ADT.` / `ADT::` call in an
+# existing install resolve to this module.
+require_relative 'devbench/version'
+require_relative 'devbench/trace'
+require_relative 'devbench/current'
+require_relative 'devbench/backtrace'
+require_relative 'devbench/identity'
+require_relative 'devbench/middleware'
+require_relative 'devbench/http'
+require_relative 'devbench/reporter'
+require_relative 'devbench/session'
+require_relative 'devbench/session_middleware'
+require_relative 'devbench/rails_hooks'
+require_relative 'devbench/sidekiq_hooks'
+
+# The pre-0.5 name. The same module object, not a copy: ADT::Middleware *is*
+# Devbench::Middleware, so a stack holding either holds the one class.
+ADT = Devbench unless defined?(::ADT)
+
+# Only under Rails. Bundler requires gems after `require 'rails'` in
+# config/application.rb, so Rails::Railtie is defined by the time this runs.
+require_relative 'devbench/railtie' if defined?(::Rails::Railtie)

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification
+name: devbench
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Dev Bench
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-05 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Reports unhandled exceptions, Rails.error reports, failed ActiveJob and
+  Sidekiq jobs, and failures the application handled, with who was
+  affected, to Dev Bench. Fingerprints and counts in-process and sends one
+  small request a minute; detail is uploaded only when Dev Bench asks for
+  it, scrubbed first. Set DEVBENCH_DSN and it hooks itself into Rails.
+
+  Adds no dependencies beyond the standard library, never alters a response
+  body, and never raises: a diagnostics gem that can fail a request is worse
+  than no diagnostics.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/adt.rb
+- lib/devbench.rb
+- lib/devbench/backtrace.rb
+- lib/devbench/config.rb
+- lib/devbench/current.rb
+- lib/devbench/direct.rb
+- lib/devbench/fingerprint.rb
+- lib/devbench/http.rb
+- lib/devbench/identity.rb
+- lib/devbench/middleware.rb
+- lib/devbench/rails_hooks.rb
+- lib/devbench/railtie.rb
+- lib/devbench/reporter.rb
+- lib/devbench/scrub.rb
+- lib/devbench/session.rb
+- lib/devbench/session_middleware.rb
+- lib/devbench/sidecar_transport.rb
+- lib/devbench/sidekiq_hooks.rb
+- lib/devbench/trace.rb
+- lib/devbench/transport.rb
+- lib/devbench/version.rb
+homepage: https://github.com/pasperry/devbench-sdk
+licenses:
+- LicenseRef-Proprietary
+metadata:
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/pasperry/devbench-sdk
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Exceptions, handled failures and who they hit, from a Rails app to Dev Bench.
+test_files: []