dispatch-rails 0.7.0

data/lib/dispatch/rails/heartbeat_aggregator.rb

@@ -0,0 +1,110 @@
+require "zlib"
+
+module Dispatch
+  module Rails
+    # Process-global, thread-safe accumulator of per-transaction request/error
+    # counts, bucketed into fixed time windows. A background thread flushes
+    # completed windows to Dispatch as a single small POST each — so the wire cost
+    # is one request per window, not one per HTTP request. The counts are the raw
+    # material for the server-side confound guard.
+    class HeartbeatAggregator
+      class << self
+        def instance
+          @instance ||= new
+        end
+
+        # Test seam.
+        def reset!
+          @instance&.stop
+          @instance = nil
+        end
+      end
+
+      def initialize
+        @mutex = Mutex.new
+        # { window_start_epoch => { "controller#action" => { requests:, errors: } } }
+        @windows = Hash.new { |h, w| h[w] = Hash.new { |t, name| t[name] = { requests: 0, errors: 0 } } }
+      end
+
+      def record(transaction:, errored:, now: Time.now)
+        return if transaction.to_s.empty?
+
+        @mutex.synchronize do
+          counts = @windows[window_for(now)][transaction]
+          counts[:requests] += 1
+          counts[:errors] += 1 if errored
+        end
+        ensure_flusher
+      end
+
+      # Payloads for every window whose time has fully elapsed; those windows are
+      # then dropped. Incomplete (current) windows are left to keep accumulating —
+      # unless include_current, which drains everything (the shutdown path, where
+      # waiting for the window to elapse means losing it).
+      def flush(now: Time.now, include_current: false)
+        @mutex.synchronize do
+          ready = @windows.keys
+          ready = ready.select { |w| w + window_seconds <= now.to_i } unless include_current
+          payloads = ready.map { |w| build_payload(w) }
+          ready.each { |w| @windows.delete(w) }
+          payloads
+        end
+      end
+
+      # Flush and ship — the unit of work the background thread repeats.
+      def deliver_ready(now: Time.now)
+        flush(now: now).each { |payload| Transport.instance.deliver_heartbeat(payload) }
+      end
+
+      # Ship everything, including the still-open window. Called at process exit
+      # so a deploy/restart doesn't drop the final window of traffic counts — the
+      # window the confound guard needs most.
+      def deliver_all(now: Time.now)
+        flush(now: now, include_current: true).each { |payload| Transport.instance.deliver_heartbeat(payload) }
+      end
+
+      def stop
+        @flusher&.kill
+        @flusher = nil
+      end
+
+      private
+
+      def build_payload(window)
+        transactions = @windows[window].transform_values do |c|
+          { "requests" => c[:requests], "errors" => c[:errors] }
+        end
+        { "window_start" => window, "transactions" => transactions }
+      end
+
+      def window_seconds
+        seconds = Dispatch::Rails.configuration.heartbeat_flush_seconds.to_i
+        seconds.positive? ? seconds : 60
+      end
+
+      def window_for(now)
+        (now.to_i / window_seconds) * window_seconds
+      end
+
+      def ensure_flusher
+        return if @flusher&.alive?
+
+        @mutex.synchronize do
+          return if @flusher&.alive?
+
+          @flusher = Thread.new do
+            loop do
+              sleep(window_seconds)
+              begin
+                deliver_ready
+              rescue StandardError => e
+                warn "[dispatch-rails] heartbeat flush failed: #{e.class}: #{e.message}"
+              end
+            end
+          end
+          @flusher.name = "dispatch-heartbeat-flusher" if @flusher.respond_to?(:name=)
+        end
+      end
+    end
+  end
+end

data/lib/dispatch/rails/heartbeat_middleware.rb

@@ -0,0 +1,60 @@
+require "zlib"
+
+module Dispatch
+  module Rails
+    # Counts every request per controller#action into the HeartbeatAggregator, so
+    # Dispatch can later tell whether a code path is still being exercised. A 5xx
+    # (or a propagating exception) counts as an errored request; everything else is
+    # a success. No-ops entirely unless traffic tracking is enabled, and never
+    # affects the response — recording failures are swallowed.
+    class HeartbeatMiddleware
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        status, headers, body = @app.call(env)
+        record(env, errored: status.to_i >= 500)
+        [status, headers, body]
+      rescue Exception # rubocop:disable Lint/RescueException
+        record(env, errored: true) # the request happened and failed
+        raise
+      end
+
+      private
+
+      def record(env, errored:)
+        config = Dispatch::Rails.configuration
+        return unless config.traffic_tracking_enabled?
+
+        transaction = transaction_for(env)
+        return if transaction.nil? || sampled_out?(config, transaction)
+
+        HeartbeatAggregator.instance.record(transaction: transaction, errored: errored)
+      rescue StandardError => e
+        warn "[dispatch-rails] heartbeat record failed: #{e.class}: #{e.message}"
+      end
+
+      def transaction_for(env)
+        ctrl = env["action_controller.instance"]
+        return nil unless ctrl
+
+        parts = [ctrl.try(:controller_name), ctrl.try(:action_name)].compact
+        parts.empty? ? nil : parts.join("#")
+      rescue StandardError
+        nil
+      end
+
+      # Independent of error_sample_rate; deterministic on transaction so a given
+      # action is always tracked-or-not (consistent counts), and at 1.0 nothing is
+      # dropped.
+      def sampled_out?(config, transaction)
+        rate = config.traffic_sample_rate.to_f
+        return false if rate >= 1.0
+        return true if rate <= 0.0
+
+        (Zlib.crc32(transaction) % 100) >= (rate * 100)
+      end
+    end
+  end
+end

data/lib/dispatch/rails/middleware.rb

@@ -0,0 +1,20 @@
+module Dispatch
+  module Rails
+    # Innermost Rack middleware: it wraps the app directly, so an unhandled
+    # exception is seen here (with the full request env, including the controller
+    # instance for user resolution) before any exception-rendering middleware.
+    # We capture and re-raise — never swallow.
+    class Middleware
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        @app.call(env)
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        Dispatch::Rails::Reporter.capture(e, handled: false, env: env)
+        raise
+      end
+    end
+  end
+end

data/lib/dispatch/rails/rake_handler.rb

@@ -0,0 +1,19 @@
+module Dispatch
+  module Rails
+    # Captures rake task failures. Rake rescues the exception itself
+    # (display_error_message, then exit(false)), so the at_exit hook only ever
+    # sees SystemExit — this is the one place the real exception is visible,
+    # with the failing command attached. Capture enqueues; the at_exit flush
+    # drains the queue before the process dies.
+    module RakeHandler
+      def display_error_message(ex)
+        Dispatch::Rails::Reporter.capture(
+          ex,
+          handled: false,
+          context: { tags: { source: "rake", command: "rake #{ARGV.join(' ')}".strip } }
+        )
+        super
+      end
+    end
+  end
+end

data/lib/dispatch/rails/reporter.rb

@@ -0,0 +1,93 @@
+require "zlib"
+
+module Dispatch
+  module Rails
+    # The capture entry point shared by the middleware and the error subscriber.
+    # Resolves the affected user, builds the event, applies client-side sampling
+    # and the before_send hook, and hands it to the transport. Never raises.
+    module Reporter
+      CAPTURED_IVAR = :@__dispatch_captured
+
+      module_function
+
+      def capture(exception, handled:, env: nil, context: {}, level: "error")
+        config = Dispatch::Rails.configuration
+        return unless config.error_tracking_enabled?
+        return unless config.environment_enabled?
+        return if already_captured?(exception)
+        return if sampled_out?(config)
+
+        mark_captured(exception)
+        user = resolve_user(config, env, context)
+        tags = merged_tags(config, env, context)
+        event = EventBuilder.call(exception, handled: handled, env: env, user: user,
+                                             tags: tags, level: level)
+        event = config.before_send.call(event) if config.before_send.respond_to?(:call)
+        return if event.nil?
+
+        Transport.instance.deliver(event)
+      rescue StandardError => e
+        warn "[dispatch-rails] capture failed: #{e.class}: #{e.message}"
+        nil
+      end
+
+      # Mark the exception object so the same instance reported again (e.g. by the
+      # Rails executor after our middleware already handled it) isn't double-sent.
+      def mark_captured(exception)
+        exception.instance_variable_set(CAPTURED_IVAR, true)
+      rescue StandardError
+        nil
+      end
+
+      def already_captured?(exception)
+        exception.instance_variable_defined?(CAPTURED_IVAR)
+      rescue StandardError
+        false
+      end
+
+      def sampled_out?(config)
+        rate = config.error_sample_rate.to_f
+        return false if rate >= 1.0
+        return true  if rate <= 0.0
+
+        rand > rate
+      end
+
+      # Tags sent with the event: the host app's explicit context[:tags] merged
+      # over whatever the config.context lambda resolves from the controller (an
+      # API-only app's seam for X-API-Key user, X-Player-ID, etc.). The explicit
+      # context[:tags] wins on conflict.
+      def merged_tags(config, env, context)
+        base = resolve_context(config, env)
+        base.merge(context[:tags] || {})
+      rescue StandardError
+        context[:tags] || {}
+      end
+
+      def resolve_context(config, env)
+        return {} unless config.context.respond_to?(:call)
+
+        controller = env && env["action_controller.instance"]
+        result = config.context.call(controller)
+        result.is_a?(Hash) ? result : {}
+      rescue StandardError
+        {}
+      end
+
+      # Reuse the SAME config.user lambda the widget uses. In a request we have the
+      # controller instance in the Rack env, so the lambda's `ctx.current_user`
+      # works exactly as configured.
+      def resolve_user(config, env, context)
+        return context[:user] if context[:user]
+        return nil unless env && config.user.respond_to?(:call)
+
+        controller = env["action_controller.instance"]
+        return nil unless controller
+
+        config.user.call(controller)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/dispatch/rails/response_annotator.rb

@@ -0,0 +1,107 @@
+require "json"
+require "cgi"
+
+module Dispatch
+  module Rails
+    # Opt-in Rack middleware (config.structured_error_responses). On 4xx/5xx
+    # responses it stamps the Rails request id — and, when a report base URL is
+    # known, a report URL — into response headers, and optionally into JSON error
+    # bodies. This is the API-only analogue of the bug-report widget: it hands the
+    # caller a correlation id they can quote when filing a curated report, which
+    # the Dispatch server then links back to the auto-captured error.
+    #
+    # It is mounted just outside ActionDispatch::ShowExceptions so it sees the
+    # FINAL rendered error response — whether the app rescued the error itself
+    # (a normal 4xx) or it propagated and ShowExceptions rendered the 500. It
+    # never changes the status code, never swallows a propagating exception, and
+    # passes through untouched anything it cannot safely parse.
+    class ResponseAnnotator
+      HEADER_REQUEST_ID = "X-Dispatch-Request-Id"
+      HEADER_REPORT_URL = "X-Dispatch-Report-Url"
+      BODY_REQUEST_ID   = "dispatch_request_id"
+      BODY_REPORT_URL   = "dispatch_report_url"
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        # @app.call is deliberately outside the rescue: if ShowExceptions re-raises
+        # (e.g. show_exceptions disabled, or in tests), the exception must keep
+        # propagating — we never swallow it.
+        status, headers, body = @app.call(env)
+        begin
+          annotate(env, status, headers, body)
+        rescue StandardError => e
+          warn "[dispatch-rails] response annotation failed: #{e.class}: #{e.message}"
+          [status, headers, body]
+        end
+      end
+
+      private
+
+      def annotate(env, status, headers, body)
+        config = Dispatch::Rails.configuration
+        return [status, headers, body] unless config.structured_error_responses
+        return [status, headers, body] unless status.to_i >= 400
+
+        request_id = env["action_dispatch.request_id"]
+        return [status, headers, body] if request_id.to_s.empty?
+
+        report_url = report_url_for(config, request_id)
+        headers[HEADER_REQUEST_ID] = request_id
+        headers[HEADER_REPORT_URL] = report_url if report_url
+
+        return [status, headers, body] unless config.annotate_error_body
+
+        annotate_body(status, headers, body, request_id, report_url)
+      end
+
+      def report_url_for(config, request_id)
+        base = config.effective_report_base_url
+        return nil if base.to_s.empty?
+
+        "#{base}/report?request_id=#{CGI.escape(request_id)}"
+      end
+
+      # Merge the correlation fields into a JSON Hash body. Anything that isn't a
+      # JSON object (HTML error pages, JSON arrays, malformed bodies) is returned
+      # unchanged. Content-Length is rewritten so the server doesn't truncate.
+      def annotate_body(status, headers, body, request_id, report_url)
+        return [status, headers, body] unless json_content?(headers)
+
+        buffer = +""
+        body.each { |part| buffer << part.to_s }
+        body.close if body.respond_to?(:close)
+
+        out = augmented_json(buffer, request_id, report_url) || buffer
+        replace_content_length!(headers, out.bytesize)
+        [status, headers, [out]]
+      end
+
+      def augmented_json(buffer, request_id, report_url)
+        parsed = JSON.parse(buffer)
+        return nil unless parsed.is_a?(Hash)
+
+        parsed[BODY_REQUEST_ID] = request_id
+        parsed[BODY_REPORT_URL] = report_url if report_url
+        JSON.generate(parsed)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def json_content?(headers)
+        content_type = headers["Content-Type"] || headers["content-type"]
+        content_type.to_s.include?("json")
+      end
+
+      # Replace Content-Length regardless of header casing (Rack 3 lowercases),
+      # so a grown/shrunk body can't be truncated by a stale length.
+      def replace_content_length!(headers, bytesize)
+        headers.delete("Content-Length")
+        headers.delete("content-length")
+        headers["Content-Length"] = bytesize.to_s
+      end
+    end
+  end
+end

data/lib/dispatch/rails/transport.rb

@@ -0,0 +1,134 @@
+require "net/http"
+require "uri"
+require "json"
+
+module Dispatch
+  module Rails
+    # Ships events to Dispatch off the request path: a single background worker
+    # drains a bounded queue and POSTs each event. Bounded so a flood can never
+    # grow memory without limit (excess events are dropped, not blocking).
+    class Transport
+      QUEUE_LIMIT = 100
+      OPEN_TIMEOUT = 2
+      READ_TIMEOUT = 5
+
+      # Sentinel pushed by #flush. The worker signals it when popped, which
+      # guarantees every event enqueued before it has been fully sent.
+      class FlushSignal
+        def initialize
+          @latch = Queue.new
+        end
+
+        def done!
+          @latch << true
+        end
+
+        def wait(timeout)
+          !@latch.pop(timeout: timeout).nil?
+        end
+      end
+
+      class << self
+        def instance
+          @instance ||= new
+        end
+
+        # Test seam.
+        def reset!
+          @instance = nil
+        end
+      end
+
+      def initialize
+        @queue = Queue.new
+        @mutex = Mutex.new
+      end
+
+      def deliver(event)
+        return if @queue.size >= QUEUE_LIMIT
+
+        ensure_worker
+        @queue << event
+        true
+      end
+
+      # Block until everything queued (and in flight) has been sent, or the
+      # deadline passes. Returns true when fully drained. Called at process
+      # exit so a shutdown doesn't drop already-captured events.
+      def flush(timeout: 3)
+        return true if @queue.empty? && @worker.nil?
+
+        signal = FlushSignal.new
+        ensure_worker
+        @queue << signal
+        signal.wait(timeout)
+      rescue StandardError
+        false
+      end
+
+      # Synchronous send of an exception event — used by tests and as the worker's
+      # unit of work. Posts to the Sentry-compatible /store endpoint.
+      def send_now(event)
+        post(Dispatch::Rails.configuration.effective_error_endpoint, event)
+      end
+
+      # Synchronous send of one flush window of traffic counts. Best-effort: a
+      # dropped heartbeat just means the confound guard has one fewer data point.
+      def deliver_heartbeat(payload)
+        post(Dispatch::Rails.configuration.effective_heartbeat_endpoint, payload)
+      end
+
+      # Synchronous curated-ticket POST backing Dispatch::Rails.report. Posts to
+      # the tickets endpoint and returns the parsed response Hash
+      # ({ "id", "status", "url" }) on success, or nil on any failure.
+      def post_ticket(payload)
+        response = post(Dispatch::Rails.configuration.endpoint, payload)
+        return nil unless response.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(response.body)
+      rescue StandardError
+        nil
+      end
+
+      private
+
+      # Shared Bearer-authenticated JSON POST. Returns the Net::HTTP response, or
+      # nil if the request itself failed. Never raises.
+      def post(endpoint, payload)
+        config = Dispatch::Rails.configuration
+        uri = URI.parse(endpoint)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = OPEN_TIMEOUT
+        http.read_timeout = READ_TIMEOUT
+
+        request = Net::HTTP::Post.new(uri.request_uri)
+        request["Content-Type"] = "application/json"
+        request["Authorization"] = "Bearer #{config.api_key}"
+        request["X-Dispatch-Sdk"] = "dispatch-rails/#{Dispatch::Rails::VERSION}"
+        request.body = JSON.generate(payload)
+
+        http.request(request)
+      rescue StandardError => e
+        warn "[dispatch-rails] failed to POST to #{endpoint}: #{e.class}: #{e.message}"
+        nil
+      end
+
+      def ensure_worker
+        return if @worker&.alive?
+
+        @mutex.synchronize do
+          return if @worker&.alive?
+
+          @worker = Thread.new do
+            loop do
+              item = @queue.pop
+              item.is_a?(FlushSignal) ? item.done! : send_now(item)
+            end
+          end
+          @worker.name = "dispatch-error-transport" if @worker.respond_to?(:name=)
+        end
+      end
+    end
+  end
+end

data/lib/dispatch/rails/version.rb

@@ -0,0 +1,5 @@
+module Dispatch
+  module Rails
+    VERSION = "0.7.0".freeze
+  end
+end

data/lib/dispatch-rails.rb

@@ -0,0 +1,108 @@
+require "dispatch/rails/version"
+require "dispatch/rails/configuration"
+require "dispatch/rails/event_builder"
+require "dispatch/rails/transport"
+require "dispatch/rails/reporter"
+require "dispatch/rails/middleware"
+require "dispatch/rails/response_annotator"
+require "dispatch/rails/heartbeat_aggregator"
+require "dispatch/rails/heartbeat_middleware"
+require "dispatch/rails/error_subscriber"
+require "dispatch/rails/rake_handler"
+require "dispatch/rails/engine"
+
+module Dispatch
+  module Rails
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def reset!
+        @configuration = Configuration.new
+      end
+
+      # Manually report a handled exception, e.g. inside a rescue:
+      #   rescue => e
+      #     Dispatch::Rails.capture_exception(e, context: { tags: { area: "import" } })
+      #   end
+      def capture_exception(exception, env: nil, context: {}, level: "error")
+        Reporter.capture(exception, handled: true, env: env, context: context, level: level)
+      end
+
+      # File a curated bug report (a ticket) programmatically — the API-only
+      # analogue of a human clicking the widget. Ideal for an AI agent or a rescue
+      # block that wants to turn a failure into a tracked, human-readable report.
+      # Pass a correlation_id (e.g. request.request_id) to link the report to an
+      # already-captured error. Synchronous — returns the created ticket's
+      # { "id", "status", "url" } Hash, or nil on failure. Never raises.
+      #
+      #   Dispatch::Rails.report(
+      #     description: "Nightly import aborted: upstream returned 502",
+      #     severity: "high",
+      #     correlation_id: request.request_id,
+      #     metadata: { job: "ImportJob" }
+      #   )
+      def report(description:, severity: nil, source: "api", metadata: {}, reporter: nil, correlation_id: nil)
+        return nil unless configuration.configured?
+
+        meta = (metadata || {}).dup
+        meta[:correlation_id] = correlation_id if correlation_id
+        ticket = {
+          description: description, source: source, severity: severity,
+          metadata: meta, reporter: reporter
+        }.compact
+        Transport.instance.post_ticket(ticket: ticket)
+      end
+
+      # Process-exit safety net: report the exception that is killing the
+      # process (a crash during boot, a dying runner/script), then ship the
+      # in-progress heartbeat window and drain the transport queue so
+      # already-captured events survive the shutdown. Exceptions captured
+      # upstream (middleware, rake handler) carry the Reporter dedup marker
+      # and aren't re-sent.
+      def install_at_exit_callback
+        return if @at_exit_installed
+
+        @at_exit_installed = true
+        at_exit { handle_at_exit($!) }
+      end
+
+      # The at_exit body, extracted so it can be exercised in tests.
+      def handle_at_exit(exception = nil)
+        if exception && !ignored_exit_exception?(exception) && configuration.capture_at_exit
+          Reporter.capture(exception, handled: false, context: { tags: { source: "at_exit" } })
+        end
+
+        timeout = configuration.shutdown_timeout.to_f
+        return unless timeout.positive?
+
+        HeartbeatAggregator.instance.deliver_all
+        Transport.instance.flush(timeout: timeout)
+      end
+
+      # Normal exits and SIGTERM-driven graceful shutdowns (deploys,
+      # scale-downs) are not crashes.
+      def ignored_exit_exception?(exception)
+        return true if exception.is_a?(SystemExit)
+        return false unless exception.is_a?(SignalException)
+
+        name = exception.respond_to?(:signm) ? exception.signm.to_s : exception.to_s
+        name.end_with?("TERM")
+      end
+    end
+  end
+end
+
+# Installed at require time (not in a Rails initializer) so a crash during
+# boot — before any initializer runs — is still reported.
+Dispatch::Rails.install_at_exit_callback
+
+# Rake is already loaded by the time a task boots the app (`rake t` /
+# `bin/rails t` load the Rakefile, which loads the environment), so prepending
+# here catches task failures. No-op outside rake.
+Rake::Application.prepend(Dispatch::Rails::RakeHandler) if defined?(::Rake::Application)