RubyGems - dispatch-rails - Versions diffs - 0.7.0 - Mend

dispatch-rails 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

checksums.yaml +7 -0
data/README.md +227 -0
data/app/assets/javascripts/dispatch/error_tracker.js +152 -0
data/app/assets/javascripts/dispatch/widget.js +293 -0
data/app/helpers/dispatch/widget_helper.rb +65 -0
data/app/views/dispatch/_error_tracker.html.erb +9 -0
data/app/views/dispatch/_widget.html.erb +71 -0
data/lib/dispatch/rails/configuration.rb +135 -0
data/lib/dispatch/rails/engine.rb +61 -0
data/lib/dispatch/rails/error_subscriber.rb +32 -0
data/lib/dispatch/rails/event_builder.rb +257 -0
data/lib/dispatch/rails/heartbeat_aggregator.rb +110 -0
data/lib/dispatch/rails/heartbeat_middleware.rb +60 -0
data/lib/dispatch/rails/middleware.rb +20 -0
data/lib/dispatch/rails/rake_handler.rb +19 -0
data/lib/dispatch/rails/reporter.rb +93 -0
data/lib/dispatch/rails/response_annotator.rb +107 -0
data/lib/dispatch/rails/transport.rb +134 -0
data/lib/dispatch/rails/version.rb +5 -0
data/lib/dispatch-rails.rb +108 -0
metadata +83 -0

data/app/helpers/dispatch/widget_helper.rb ADDED Viewed

@@ -0,0 +1,65 @@
+module Dispatch
+  module WidgetHelper
+    # Render the floating bug-report widget.
+    #
+    # Options:
+    #   severity:       one of "low", "medium", "high", "critical" — pre-classifies reports
+    #                   from this page (useful for marking a /checkout page as critical-by-default)
+    #   labels:         array of strings merged into metadata.labels so reports can be tagged per-surface
+    #   extra_metadata: arbitrary hash merged into the metadata blob
+    def dispatch_widget_tag(severity: nil, labels: nil, extra_metadata: {})
+      config = Dispatch::Rails.configuration
+      return nil if config.errors_only? # headless / API-only apps have no widget
+      return nil unless config.configured?
+      user = config.user.respond_to?(:call) ? config.user.call(self) : nil
+      base_metadata = config.metadata.respond_to?(:call) ? config.metadata.call(self) : {}
+      page_metadata = base_metadata.to_h.merge(extra_metadata)
+      page_metadata[:labels] = Array(labels).map(&:to_s) if labels.present?
+      page_metadata[:severity_hint] = severity.to_s if severity.present?
+      render(
+        partial: "dispatch/widget",
+        locals: {
+          api_key: config.api_key,
+          endpoint: config.endpoint,
+          user: user,
+          metadata: page_metadata,
+          severity: severity&.to_s,
+          capture_console: config.capture_console,
+          capture_clicks: config.capture_clicks,
+          button_position: config.button_position
+        }
+      )
+    end
+    # Render the browser exception tracker (captures uncaught JS errors and
+    # unhandled promise rejections). Place once in your layout's <head>.
+    def dispatch_error_tracker_tag(tags: {})
+      config = Dispatch::Rails.configuration
+      return nil if config.errors_only? # no browser surface in an API-only app
+      return nil unless config.configured? && config.capture_browser_errors
+      return nil unless config.environment_enabled?
+      user = config.user.respond_to?(:call) ? config.user.call(self) : nil
+      normalized_user = user && { email: user[:email], id: user[:external_id] || user[:id] }.compact
+      render(
+        partial: "dispatch/error_tracker",
+        locals: {
+          error_config_json: {
+            endpoint: config.effective_error_endpoint,
+            apiKey: config.api_key,
+            environment: config.effective_environment,
+            release: config.release,
+            sampleRate: config.error_sample_rate,
+            captureClicks: config.capture_clicks,
+            user: normalized_user,
+            tags: tags
+          }.to_json
+        }
+      )
+    end
+  end
+end

data/app/views/dispatch/_error_tracker.html.erb ADDED Viewed

@@ -0,0 +1,9 @@
+<script type="application/json" id="dispatch-error-config"><%= raw error_config_json.gsub("</", "<\\/") %></script>
+<%# nonce: true picks up the host app's CSP nonce; the JSON config island above is non-executable and needs none %>
+<%= javascript_tag type: "module", nonce: true do %>
+  if (!window.__dispatchErrorTrackerLoaded) {
+    import("/dispatch/error_tracker.js").catch(() => {
+      console.error("[dispatch-rails] failed to load error_tracker.js — ensure the engine assets are mounted");
+    });
+  }
+<% end %>

data/app/views/dispatch/_widget.html.erb ADDED Viewed

@@ -0,0 +1,71 @@
+<div data-controller="dispatch-widget"
+     data-dispatch-widget-endpoint-value="<%= endpoint %>"
+     data-dispatch-widget-api-key-value="<%= api_key %>"
+     data-dispatch-widget-user-value="<%= user.to_json %>"
+     data-dispatch-widget-metadata-value="<%= metadata.to_json %>"
+     data-dispatch-widget-severity-value="<%= severity %>"
+     data-dispatch-widget-capture-console-value="<%= capture_console %>"
+     data-dispatch-widget-capture-clicks-value="<%= capture_clicks %>">
+  <button type="button"
+          data-action="click->dispatch-widget#open"
+          data-dispatch-widget-target="button"
+          aria-label="Send feedback"
+          style="position:fixed;<%= button_position.include?('bottom') ? 'bottom:24px' : 'top:24px' %>;<%= button_position.include?('right') ? 'right:24px' : 'left:24px' %>;width:56px;height:56px;border-radius:9999px;background:#2563eb;color:#fff;border:none;box-shadow:0 8px 24px rgba(37,99,235,0.35);cursor:pointer;font-size:24px;display:flex;align-items:center;justify-content:center;z-index:9999;">
+    💬
+  </button>
+  <div data-dispatch-widget-target="modal"
+       hidden
+       style="position:fixed;inset:0;background:rgba(0,0,0,0.6);display:flex;align-items:center;justify-content:center;z-index:10000;">
+    <div data-dispatch-widget-target="dropzone"
+         data-action="dragover->dispatch-widget#dragover dragleave->dispatch-widget#dragleave drop->dispatch-widget#drop paste->dispatch-widget#paste"
+         style="background:#0a0a0a;color:#e5e7eb;border:1px solid #1f2937;border-radius:12px;padding:24px;width:min(480px,calc(100% - 32px));font-family:ui-sans-serif,system-ui,sans-serif;">
+      <div style="display:flex;justify-content:space-between;align-items:center;margin-bottom:12px;">
+        <h2 style="font-family:ui-monospace,monospace;letter-spacing:0.05em;color:#60a5fa;margin:0;">SEND FEEDBACK</h2>
+        <button type="button" data-action="click->dispatch-widget#close" style="background:none;border:none;color:#9ca3af;font-size:20px;cursor:pointer;">×</button>
+      </div>
+      <p style="font-size:13px;color:#9ca3af;margin:0 0 12px;">Found a bug, want a feature, or think something should work differently? Tell us. We'll capture the URL, browser, and environment automatically.</p>
+      <textarea data-dispatch-widget-target="description"
+                rows="5"
+                placeholder="When I clicked Save, the page returned a 500… or: It'd be great if I could export this list as CSV."
+                style="width:100%;background:#0a0a0a;color:#e5e7eb;border:1px solid #1f2937;border-radius:6px;padding:10px;font-family:ui-monospace,monospace;font-size:13px;box-sizing:border-box;"></textarea>
+      <input type="file"
+             data-dispatch-widget-target="fileInput"
+             data-action="change->dispatch-widget#filesPicked"
+             accept="image/png,image/jpeg,image/gif,image/webp"
+             multiple
+             hidden>
+      <div style="display:flex;align-items:center;gap:10px;margin-top:10px;flex-wrap:wrap;">
+        <button type="button"
+                data-action="click->dispatch-widget#openFilePicker"
+                data-dispatch-widget-target="attachButton"
+                style="padding:6px 12px;background:#1f2937;border:1px solid #374151;color:#e5e7eb;border-radius:6px;cursor:pointer;font-family:ui-monospace,monospace;font-size:12px;">📎 Attach screenshots (0/5)</button>
+        <span style="font-size:11px;color:#6b7280;">or paste / drag &amp; drop · max 5, 5&nbsp;MB each</span>
+      </div>
+      <div data-dispatch-widget-target="previews" style="display:flex;flex-wrap:wrap;gap:8px;margin-top:10px;"></div>
+      <div data-dispatch-widget-target="error" style="color:#f87171;font-size:12px;margin-top:8px;display:none;"></div>
+      <div style="display:flex;gap:8px;justify-content:flex-end;margin-top:16px;">
+        <button type="button" data-action="click->dispatch-widget#close" style="padding:8px 14px;background:#1f2937;border:1px solid #374151;color:#e5e7eb;border-radius:6px;cursor:pointer;font-family:ui-monospace,monospace;font-size:13px;">Cancel</button>
+        <button type="button" data-action="click->dispatch-widget#submit" data-dispatch-widget-target="submit" style="padding:8px 14px;background:#2563eb;border:none;color:#fff;border-radius:6px;cursor:pointer;font-family:ui-monospace,monospace;font-size:13px;">Send</button>
+      </div>
+    </div>
+  </div>
+  <div data-dispatch-widget-target="toast"
+       hidden
+       style="position:fixed;bottom:24px;left:50%;transform:translateX(-50%);background:#064e3b;color:#a7f3d0;border:1px solid #34d399;border-radius:6px;padding:10px 16px;font-family:ui-monospace,monospace;font-size:13px;z-index:10001;box-shadow:0 8px 24px rgba(0,0,0,0.4);">
+    ✓ Feedback sent. Thanks!
+  </div>
+</div>
+<%# nonce: true picks up the host app's CSP nonce; omitted when no nonce generator is configured %>
+<%= javascript_tag type: "module", nonce: true do %>
+  if (!window.__dispatchWidgetLoaded) {
+    window.__dispatchWidgetLoaded = true;
+    import("/dispatch/widget.js").catch(() => {
+      console.error("[dispatch-rails] failed to load widget.js — make sure the engine assets are mounted");
+    });
+  }
+<% end %>

data/lib/dispatch/rails/configuration.rb ADDED Viewed

@@ -0,0 +1,135 @@
+require "uri"
+module Dispatch
+  module Rails
+    class Configuration
+      # Install mode. :widget is the default (a UI app embeds the bug-report
+      # button); :errors_only is for API-only / headless apps that have no UI to
+      # render into — server-side exception capture and manual reporting still
+      # work, but the widget and browser-error tags become no-ops.
+      MODES = %i[widget errors_only].freeze
+      # Bug-report widget
+      attr_accessor :api_key, :endpoint, :user, :metadata, :capture_console, :capture_clicks, :button_position
+      # Mode + API-only context
+      attr_accessor :mode, :context, :send_default_params
+      # Exception tracking
+      attr_accessor :capture_exceptions, :capture_browser_errors, :error_endpoint,
+                    :environment, :release, :enabled_environments, :error_sample_rate, :before_send
+      # Process lifecycle (crash-at-exit capture, rake failures, shutdown flush)
+      attr_accessor :capture_at_exit, :shutdown_timeout
+      # Structured error responses (API-only)
+      attr_accessor :structured_error_responses, :annotate_error_body, :report_base_url
+      # Traffic heartbeats — per-transaction success counts that let the Dispatch
+      # server tell "the error stopped because we fixed it" from "…because the
+      # path went quiet" (the confound guard behind fix verification).
+      attr_accessor :capture_traffic, :traffic_sample_rate, :heartbeat_flush_seconds, :heartbeat_endpoint
+      def initialize
+        @api_key = nil
+        @endpoint = "https://dispatchit.app/api/v1/tickets"
+        @user = ->(_ctx) { nil }
+        @metadata = ->(_ctx) { {} }
+        @capture_console = false
+        @capture_clicks = true # track the last few clicks as a "user path" for context
+        @button_position = "bottom-right"
+        # Mode + API-only context
+        @mode = :widget
+        @context = ->(_ctx) { {} } # extra tags resolved from the controller (API key user, headers, …)
+        @send_default_params = false # opt-in: include Rails' filtered_parameters in the event
+        # Exception tracking defaults
+        @capture_exceptions = true
+        @capture_browser_errors = true
+        @error_endpoint = nil # derived from endpoint when nil
+        @environment = nil    # derived from Rails.env when nil
+        @release = nil        # e.g. ENV["GIT_SHA"]
+        @enabled_environments = %w[production staging]
+        @error_sample_rate = 1.0
+        @before_send = nil    # ->(event) { event or nil to drop }
+        # Process lifecycle. Report the exception killing the process (a crash
+        # during boot, a dying runner) and drain the send queue before exit so
+        # deploys/restarts don't drop captured events.
+        @capture_at_exit = true
+        @shutdown_timeout = 3 # seconds to wait for the queue to drain at exit; 0 skips the flush
+        # Structured error responses (off by default — opt-in so we never alter a
+        # host app's error contract without being asked).
+        @structured_error_responses = false
+        @annotate_error_body = false # headers-only unless explicitly enabled
+        @report_base_url = nil       # derived from endpoint host when nil
+        # Traffic heartbeats. On by default in enabled environments: aggregate
+        # counts only (one small POST per flush window, regardless of request
+        # volume), so the cost is negligible and the confound guard works out of
+        # the box. Sampling is independent of error_sample_rate.
+        @capture_traffic = true
+        @traffic_sample_rate = 1.0
+        @heartbeat_flush_seconds = 60
+        @heartbeat_endpoint = nil # derived from endpoint when nil
+      end
+      def configured?
+        api_key.present? && endpoint.present?
+      end
+      def errors_only?
+        mode.to_sym == :errors_only
+      rescue StandardError
+        false
+      end
+      # Where exception events are posted. Defaults to the same host as the widget
+      # endpoint with the path swapped to the Sentry-compatible /store endpoint.
+      def effective_error_endpoint
+        return @error_endpoint if @error_endpoint.present?
+        endpoint.to_s.sub(%r{/[^/]+\z}, "/store")
+      end
+      # The base URL (scheme + host) where the Dispatch tenant lives, used to build
+      # the human-facing report link surfaced in structured error responses.
+      # Falls back to the origin of `endpoint` (https://dispatchit.app).
+      def effective_report_base_url
+        return @report_base_url.to_s.chomp("/") if @report_base_url.present?
+        uri = URI.parse(endpoint.to_s)
+        return nil if uri.host.nil?
+        port = uri.port && ![80, 443].include?(uri.port) ? ":#{uri.port}" : ""
+        "#{uri.scheme}://#{uri.host}#{port}"
+      rescue StandardError
+        nil
+      end
+      # Where per-transaction traffic rollups are posted. Defaults to the same host
+      # as the widget endpoint with the path swapped to /heartbeats.
+      def effective_heartbeat_endpoint
+        return @heartbeat_endpoint if @heartbeat_endpoint.present?
+        endpoint.to_s.sub(%r{/[^/]+\z}, "/heartbeats")
+      end
+      def effective_environment
+        @environment.presence || (defined?(::Rails) && ::Rails.respond_to?(:env) ? ::Rails.env.to_s : "production")
+      end
+      def error_tracking_enabled?
+        configured? && @capture_exceptions
+      end
+      # Heartbeats piggyback on the same gating as error capture, plus their own
+      # toggle. Off in non-enabled environments (so dev/test never phone home).
+      def traffic_tracking_enabled?
+        @capture_traffic && error_tracking_enabled? && environment_enabled?
+      end
+      def environment_enabled?
+        list = Array(@enabled_environments).map(&:to_s)
+        list.empty? || list.include?(effective_environment)
+      end
+    end
+  end
+end

data/lib/dispatch/rails/engine.rb ADDED Viewed

@@ -0,0 +1,61 @@
+require "rails"
+module Dispatch
+  module Rails
+    class Engine < ::Rails::Engine
+      isolate_namespace Dispatch::Rails
+      # Expose the widget/tracker helpers to HOST app views. The engine is
+      # isolated, so Rails won't share its helpers automatically — and registering
+      # from inside the helper file only works when something loads that file,
+      # which eager loading does in production but nothing does in development
+      # (the layout's dispatch_widget_tag call would raise NoMethodError there).
+      # to_prepare runs at boot and on every code reload, where autoloading the
+      # reloadable helper constant is permitted.
+      config.to_prepare do
+        ActiveSupport.on_load(:action_view) { include Dispatch::WidgetHelper }
+      end
+      initializer "dispatch-rails.assets" do |app|
+        if app.config.respond_to?(:assets)
+          app.config.assets.paths << root.join("app/assets/javascripts").to_s
+        end
+        if defined?(::Importmap) && app.respond_to?(:importmap)
+          # Host app can pin "dispatch-widget" / "dispatch-error-tracker" in its importmap.
+        end
+      end
+      # Server-side exception capture. The middleware is added last (innermost),
+      # so it wraps the app directly and sees raw exceptions with full request
+      # context before any exception-rendering middleware.
+      initializer "dispatch-rails.error_capture" do |app|
+        app.config.middleware.use Dispatch::Rails::Middleware
+        # Catch background/non-request errors (ActiveJob, runners, handle blocks).
+        if ::Rails.respond_to?(:error) && ::Rails.error.respond_to?(:subscribe)
+          ::Rails.error.subscribe(Dispatch::Rails::ErrorSubscriber.new)
+        end
+      end
+      # Per-transaction traffic heartbeats. Mounted unconditionally; the middleware
+      # no-ops at request time unless config.traffic_tracking_enabled? (false in
+      # dev/test), so it never phones home outside enabled environments.
+      initializer "dispatch-rails.traffic_heartbeats" do |app|
+        app.config.middleware.use Dispatch::Rails::HeartbeatMiddleware
+      end
+      # Structured error responses (API-only). Inserted just OUTSIDE
+      # ActionDispatch::ShowExceptions so it sees the final rendered error
+      # response — both app-rescued 4xx and propagated-then-rendered 500s — and so
+      # action_dispatch.request_id (set further out by RequestId) is populated.
+      # Mounted unconditionally; it no-ops at request time unless the host opted in
+      # via config.structured_error_responses, which sidesteps boot-order races
+      # with the host's initializer.
+      initializer "dispatch-rails.structured_responses" do |app|
+        app.config.middleware.insert_before(
+          ActionDispatch::ShowExceptions, Dispatch::Rails::ResponseAnnotator
+        )
+      end
+    end
+  end
+end

data/lib/dispatch/rails/error_subscriber.rb ADDED Viewed

@@ -0,0 +1,32 @@
+module Dispatch
+  module Rails
+    # Subscribes to Rails.error (ActiveSupport::ErrorReporter). Catches errors
+    # outside the web request — ActiveJob failures, runners, and explicit
+    # Rails.error.handle/record blocks. Request errors already captured by the
+    # Rack middleware carry a marker and are skipped here, so nothing is
+    # double-counted.
+    class ErrorSubscriber
+      SEVERITY_TO_LEVEL = { error: "error", warning: "warning", info: "info" }.freeze
+      def report(error, handled:, severity: :error, context: {}, source: nil)
+        return if source.to_s.start_with?("dispatch")
+        Dispatch::Rails::Reporter.capture(
+          error,
+          handled: handled,
+          context: { tags: context_tags(context, source) },
+          level: SEVERITY_TO_LEVEL.fetch(severity, "error")
+        )
+      end
+      private
+      def context_tags(context, source)
+        tags = {}
+        tags[:source] = source.to_s if source
+        tags[:job] = context[:job_class] if context.is_a?(Hash) && context[:job_class]
+        tags
+      end
+    end
+  end
+end

data/lib/dispatch/rails/event_builder.rb ADDED Viewed

@@ -0,0 +1,257 @@
+require "securerandom"
+require "socket"
+require "json"
+module Dispatch
+  module Rails
+    # Turns a Ruby exception (+ optional Rack env / user) into the Sentry-shaped
+    # event hash the Dispatch ingest endpoint understands. In-app frames are
+    # flagged and given source context (the lines around the failing line), which
+    # is what makes the AI fix pipeline's patches accurate.
+    class EventBuilder
+      CONTEXT_LINES       = 5
+      MAX_CONTEXT_FRAMES  = 12
+      MAX_FRAMES          = 100
+      MAX_CAUSES          = 5
+      MAX_PARAMS_BYTES    = 8_000
+      SAFE_HEADERS        = %w[User-Agent Referer Accept Content-Type Host X-Request-Id].freeze
+      def self.call(exception, handled:, env: nil, user: nil, tags: {}, level: "error")
+        new(exception, handled: handled, env: env, user: user, tags: tags, level: level).call
+      end
+      def initialize(exception, handled:, env: nil, user: nil, tags: {}, level: "error")
+        @exception = exception
+        @handled = handled
+        @env = env
+        @user = user
+        @tags = tags || {}
+        @level = level
+        @source_cache = {}
+        @config = Dispatch::Rails.configuration
+      end
+      def call
+        {
+          event_id: SecureRandom.uuid.delete("-"),
+          timestamp: Time.now.to_f,
+          platform: "ruby",
+          level: @level,
+          environment: @config.effective_environment,
+          release: @config.release,
+          server_name: hostname,
+          transaction: transaction, # Sentry's name for the controller#action
+          exception: { values: exception_values },
+          request: request_hash,
+          user: user_hash,
+          tags: tags_hash,
+          sdk: { name: "dispatch-rails", version: Dispatch::Rails::VERSION }
+        }.compact
+      end
+      private
+      # The Rails request id (always present under Rails) doubles as the public
+      # correlation key surfaced in structured error responses, so a human-curated
+      # report can be tied back to this captured event server-side.
+      def request_id
+        return @request_id if defined?(@request_id)
+        @request_id = @env && @env["action_dispatch.request_id"]
+      end
+      # "players#show" — derived from the controller in the Rack env. nil for
+      # background/job errors where there is no controller.
+      def transaction
+        return @transaction if defined?(@transaction)
+        @transaction = begin
+          ctrl = controller_instance
+          parts = ctrl && [ctrl.try(:controller_name), ctrl.try(:action_name)].compact
+          parts.present? ? parts.join("#") : nil
+        rescue StandardError
+          nil
+        end
+      end
+      def controller_instance
+        @env && @env["action_controller.instance"]
+      end
+      # Surface request_id and transaction as tags too (handy for filtering in the
+      # dashboard). The host app's explicit tags win on any key conflict.
+      def tags_hash
+        derived = { request_id: request_id, transaction: transaction }.compact
+        derived.merge(@tags)
+      end
+      def exception_values
+        chain = []
+        exc = @exception
+        MAX_CAUSES.times do
+          break if exc.nil?
+          chain << exc
+          exc = exc.cause
+        end
+        # Sentry expects oldest cause first, the raised exception last.
+        chain.reverse.map { |e| exception_value(e) }
+      end
+      def exception_value(exc)
+        {
+          type: exc.class.name,
+          value: exc.message.to_s[0, 2_000],
+          mechanism: { type: "generic", handled: @handled },
+          stacktrace: { frames: frames_for(exc) }
+        }
+      end
+      def frames_for(exc)
+        locations = exc.backtrace_locations
+        raw = locations || Array(exc.backtrace).map { |line| parse_line(line) }.compact
+        # newest-first → reverse to oldest-first (failing frame last, Sentry-style)
+        frames = raw.first(MAX_FRAMES).reverse.map { |loc| frame_for(loc) }.compact
+        annotate_context(frames)
+        frames
+      end
+      def frame_for(loc)
+        if loc.respond_to?(:absolute_path)
+          path = loc.absolute_path || loc.path
+          { abs_path: path, function: loc.label, lineno: loc.lineno }
+        else
+          loc # already a hash from parse_line
+        end.then do |h|
+          path = h[:abs_path]
+          {
+            abs_path: path,
+            filename: relative_path(path),
+            function: h[:function],
+            lineno: h[:lineno],
+            in_app: in_app?(path)
+          }.compact
+        end
+      end
+      # "/path/to/file.rb:42:in `method'"
+      def parse_line(line)
+        match = line.match(/\A(.+?):(\d+):in [`'](.+)'\z/) || line.match(/\A(.+?):(\d+)\z/)
+        return nil unless match
+        { abs_path: match[1], lineno: match[2].to_i, function: match[3] }
+      end
+      # Add source context to the most-recent in-app frames (the tail of the array).
+      def annotate_context(frames)
+        budget = MAX_CONTEXT_FRAMES
+        frames.reverse_each do |frame|
+          next unless frame[:in_app] && budget.positive?
+          budget -= 1
+          add_source_context(frame)
+        end
+      end
+      def add_source_context(frame)
+        lines = source_lines(frame[:abs_path])
+        return unless lines && frame[:lineno]
+        idx = frame[:lineno] - 1
+        return if idx.negative? || idx >= lines.length
+        frame[:pre_context]  = lines[[idx - CONTEXT_LINES, 0].max...idx].map(&:rstrip)
+        frame[:context_line] = lines[idx].rstrip
+        frame[:post_context] = lines[(idx + 1)..(idx + CONTEXT_LINES)].to_a.map(&:rstrip)
+      end
+      def source_lines(path)
+        return nil if path.nil? || !File.file?(path)
+        @source_cache[path] ||= File.readlines(path, chomp: true)
+      rescue StandardError
+        nil
+      end
+      def in_app?(path)
+        return false if path.nil?
+        path.start_with?(project_root) && !path.include?("/gems/") &&
+          !path.include?("/vendor/") && !path.include?("/ruby/")
+      end
+      def relative_path(path)
+        return path if path.nil?
+        path.start_with?(project_root) ? path[project_root.length..].sub(%r{\A/}, "") : path
+      end
+      def project_root
+        @project_root ||= (defined?(::Rails) && ::Rails.respond_to?(:root) && ::Rails.root ? ::Rails.root.to_s : Dir.pwd)
+      end
+      def request_hash
+        return nil if @env.nil?
+        {
+          url: request_url,
+          method: @env["REQUEST_METHOD"],
+          query_string: @env["QUERY_STRING"].presence,
+          headers: safe_headers,
+          data: request_data,
+          env: { "REMOTE_ADDR" => @env["REMOTE_ADDR"] }.compact
+        }.compact
+      end
+      # Opt-in (config.send_default_params). Uses Rails' own filtered_parameters,
+      # so the host app's config.filter_parameters has already redacted secrets.
+      # Capped by byte size; the controller/action/format routing keys are dropped.
+      def request_data
+        return nil unless @config.send_default_params
+        ctrl = controller_instance
+        return nil unless ctrl.respond_to?(:request)
+        params = ctrl.request.filtered_parameters.except("controller", "action", "format")
+        return nil if params.blank?
+        JSON.generate(params).bytesize > MAX_PARAMS_BYTES ? { "_truncated" => true } : params
+      rescue StandardError
+        nil
+      end
+      def request_url
+        scheme = @env["rack.url_scheme"] || "http"
+        host = @env["HTTP_HOST"] || @env["SERVER_NAME"]
+        return nil if host.nil?
+        "#{scheme}://#{host}#{@env['PATH_INFO']}"
+      end
+      def safe_headers
+        SAFE_HEADERS.each_with_object({}) do |name, out|
+          key = "HTTP_#{name.upcase.tr('-', '_')}"
+          value = @env[key] || (@env[name.upcase.tr("-", "_")] if name == "Content-Type")
+          out[name] = value if value
+        end
+      end
+      def user_hash
+        return nil if @user.nil?
+        hash = @user.respond_to?(:to_h) ? @user.to_h : {}
+        {
+          id: (hash[:id] || hash[:external_id] || hash["id"] || hash["external_id"])&.to_s,
+          email: hash[:email] || hash["email"],
+          ip_address: @env && @env["REMOTE_ADDR"]
+        }.compact.presence
+      end
+      def hostname
+        Socket.gethostname
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end