dispatch-rails 0.7.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 300eb860cc2bb5f7dff2322818cc6bd552507695c71c84c9be81ccbd6e34a3fd
-  data.tar.gz: 4070748d3d36256a456e9eb960d36c47418ec55f699e0984a9fd49c4d67b501f
+  metadata.gz: eb09ad358ca9afa12624a37603693b0892b3816a1733852a6e5bddec3f7e0ad8
+  data.tar.gz: 6d877756e23368e5bc033fb4696709b464eb957a1b76a3106e37e1c876cb91db
 SHA512:
-  metadata.gz: 1dcbd3e9a81c078086e62e5e50bca81679832a2dff5e5fd1fe5b4a82bc052e445adb83dbc8e1f7c22b8699e94d6a7d5a6d843d2ae7f974a97cabf682289d767d
-  data.tar.gz: 21765b8506a454e84d225b8d932ce6a15dc2cddd948d8247cddae59908cfe1499139f607a90892e1dffa247a299f156b3c09e1100a73efeb2ae8243af9a7a133
+  metadata.gz: 02e6876ac14a61b0215ae79eb52bf47fe632e3dd3ed676c9706921552e1fc73d3a208f21b07047484b9ee8c3e9a5aa9eb58d018b83f17bf80ce6c0609ac95ebe
+  data.tar.gz: c22f0667ea5fa682f27f2273f1c3630cc54ffa657694830342dea94b7f5e6c693492b0e82cb006438c7373a2cf6be1a7be3e16203f5927440a9ebb5f54963a24

data/README.md

@@ -128,6 +128,28 @@ quote. With `c.annotate_error_body = true`, the same fields (`dispatch_request_i
 they sit beside `type`/`title`/`detail`). The middleware never changes status codes
 and passes through anything it can't safely parse.
 
+### Browser CSP & Reporting API
+
+CSP violations and other browser-native reports (NEL, deprecation, intervention)
+never reach `window.onerror`, so the SDK captures them two ways — pick **one** for
+CSP, or a violation reported through both is counted twice. Both are opt-in.
+
+```ruby
+# 1. Client-side: the JS error tracker also listens for SecurityPolicyViolationEvents.
+#    Needs dispatch_error_tracker_tag in your layout (it already loads the tracker).
+c.capture_csp_violations = true
+
+# 2. Server-side: a Rack endpoint accepts the browser's NATIVE report POSTs — point a
+#    CSP report-uri/report-to (or any Reporting-Endpoints group) at the path below and
+#    the browser posts straight to Dispatch. No host controller required.
+c.capture_browser_reports = true
+c.reporting_endpoint_path = "/dispatch/reports"  # default; must be a path no route uses
+```
+
+Option 2 also ingests non-CSP Reporting-API types (deprecation, intervention, NEL).
+Reports flow through `error_sample_rate` and `before_send` like any other event, so
+host-specific noise (browser-extension schemes, autofill) is best filtered there.
+
 ### Curated reports (programmatic / agent)
 
 A consumer (or an AI agent inside your app) turns a failure into a tracked report:

data/app/assets/javascripts/dispatch/error_tracker.js

@@ -106,6 +106,45 @@
     };
   }
 
+  // CSP violations never reach window.onerror — the browser fires a dedicated
+  // SecurityPolicyViolationEvent. We synthesize a single stack frame from the
+  // violation's source location so the dashboard can point at the offending file.
+  function buildCspEvent(e) {
+    var directive = e.effectiveDirective || e.violatedDirective || "policy";
+    var blocked = e.blockedURI || "inline";
+    var frames = (e.sourceFile && e.lineNumber) ? [{
+      function: "?", filename: e.sourceFile, abs_path: e.sourceFile,
+      lineno: parseInt(e.lineNumber, 10) || 0, colno: parseInt(e.columnNumber, 10) || 0,
+      in_app: String(e.sourceFile).indexOf("http") === 0
+    }] : [];
+    return {
+      event_id: uuid(),
+      timestamp: now(),
+      platform: "javascript",
+      // report-only disposition is monitoring, not a live block — keep it quieter.
+      level: e.disposition === "report" ? "info" : "warning",
+      environment: cfg.environment,
+      release: cfg.release,
+      exception: { values: [{
+        type: "SecurityPolicyViolation",
+        value: (directive + " blocked " + blocked).slice(0, 2000),
+        mechanism: { type: "securitypolicyviolation", handled: false },
+        stacktrace: { frames: frames }
+      }] },
+      breadcrumbs: { values: breadcrumbs.slice() },
+      user_path: userPath(),
+      request: { url: e.documentURI || location.href, headers: { "User-Agent": navigator.userAgent } },
+      user: cfg.user || null,
+      tags: Object.assign({
+        csp: "true",
+        blocked_uri: blocked,
+        violated_directive: e.violatedDirective || directive,
+        effective_directive: directive,
+        disposition: e.disposition || "enforce"
+      }, cfg.tags || {})
+    };
+  }
+
   function sampledOut() {
     var rate = cfg.sampleRate == null ? 1 : cfg.sampleRate;
     return Math.random() > rate;
@@ -143,6 +182,21 @@
     send(buildEvent(r.name || "UnhandledRejection", value, r.stack));
   });
 
+  // Opt-in (cfg.captureCsp): a permissive or report-only policy can fire these in
+  // bulk, so we dedupe per page — a violation repeated on every render (e.g. a
+  // blocked image) is reported once. Bounded so a page spraying unique blocked
+  // URIs can't grow the key set without limit.
+  if (cfg.captureCsp) {
+    var seenCsp = {};
+    var seenCspCount = 0;
+    document.addEventListener("securitypolicyviolation", function (e) {
+      var key = [e.effectiveDirective, e.blockedURI, e.sourceFile, e.lineNumber].join("|");
+      if (seenCsp[key]) return;
+      if (seenCspCount < 200) { seenCsp[key] = 1; seenCspCount++; }
+      send(buildCspEvent(e));
+    });
+  }
+
   // Manual capture API: window.Dispatch.captureException(error)
   window.Dispatch = window.Dispatch || {};
   window.Dispatch.captureException = function (err) {

data/app/helpers/dispatch/widget_helper.rb

@@ -35,7 +35,8 @@ module Dispatch
     end
 
     # Render the browser exception tracker (captures uncaught JS errors and
-    # unhandled promise rejections). Place once in your layout's <head>.
+    # unhandled promise rejections — and, when config.capture_csp_violations is on,
+    # SecurityPolicyViolationEvents). 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
@@ -55,6 +56,7 @@ module Dispatch
             release: config.release,
             sampleRate: config.error_sample_rate,
             captureClicks: config.capture_clicks,
+            captureCsp: config.capture_csp_violations,
             user: normalized_user,
             tags: tags
           }.to_json

data/lib/dispatch/rails/configuration.rb

@@ -16,6 +16,8 @@ module Dispatch
       # Exception tracking
       attr_accessor :capture_exceptions, :capture_browser_errors, :error_endpoint,
                     :environment, :release, :enabled_environments, :error_sample_rate, :before_send
+      # Browser security/reporting capture (both opt-in; high-volume + noise-prone)
+      attr_accessor :capture_csp_violations, :capture_browser_reports, :reporting_endpoint_path
       # Process lifecycle (crash-at-exit capture, rake failures, shutdown flush)
       attr_accessor :capture_at_exit, :shutdown_timeout
       # Structured error responses (API-only)
@@ -49,6 +51,16 @@ module Dispatch
         @error_sample_rate = 1.0
         @before_send = nil    # ->(event) { event or nil to drop }
 
+        # Browser security/reporting capture. Both opt-in: a permissive or
+        # report-only CSP can emit these in bulk, and capture_browser_reports also
+        # makes the gem own a URL path. Pick ONE CSP mechanism — the JS
+        # securitypolicyviolation listener (capture_csp_violations) OR the native
+        # report endpoint (capture_browser_reports) — or a violation reported
+        # through both is counted twice.
+        @capture_csp_violations = false   # JS: listen for SecurityPolicyViolationEvent
+        @capture_browser_reports = false  # Server: accept native browser report POSTs
+        @reporting_endpoint_path = "/dispatch/reports"
+
         # 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.
@@ -120,6 +132,13 @@ module Dispatch
         configured? && @capture_exceptions
       end
 
+      # Fast-path guard for ReportingEndpointMiddleware: own the reporting path only
+      # when the host opted in and we have credentials to deliver. Otherwise the
+      # middleware passes the request straight through (no surprise 204s).
+      def browser_reports_enabled?
+        configured? && @capture_browser_reports
+      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?

data/lib/dispatch/rails/engine.rb

@@ -31,6 +31,14 @@ module Dispatch
       initializer "dispatch-rails.error_capture" do |app|
         app.config.middleware.use Dispatch::Rails::Middleware
 
+        # Native browser Reporting API endpoint (CSP report-uri/report-to, NEL,
+        # deprecation, …). Mounted unconditionally; owns
+        # config.reporting_endpoint_path only when the host opts in via
+        # config.capture_browser_reports, and passes through otherwise. Sits just
+        # inside the capture middleware so a report POST short-circuits to 204
+        # before the heartbeat/router layers below it.
+        app.config.middleware.use Dispatch::Rails::ReportingEndpointMiddleware
+
         # 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)

data/lib/dispatch/rails/reporting_endpoint_middleware.rb

@@ -0,0 +1,172 @@
+require "json"
+
+module Dispatch
+  module Rails
+    # A report the browser delivered through the native Reporting API (deprecation,
+    # intervention, NEL, …) — not a Ruby error and not a JS exception.
+    class BrowserReport < StandardError; end
+    # A Content-Security-Policy violation delivered by the browser's native
+    # report-uri/report-to channel. CSP violations never reach window.onerror, so
+    # nothing surfaces them unless the browser is told to POST a report here.
+    class CspViolation < BrowserReport; end
+
+    # Terminal Rack endpoint for the browser Reporting API. Point a CSP
+    # `report-uri`/`report-to` group (or any Reporting-Endpoints group) at
+    # config.reporting_endpoint_path and the browser POSTs its reports straight
+    # here — no host controller required. Each report becomes a synthetic exception
+    # pushed through Reporter.capture, so it lands as a first-class event with the
+    # usual sampling, before_send, and transport applied.
+    #
+    # Opt-in (config.capture_browser_reports). When disabled — or for any request
+    # that isn't a POST to the configured path — it passes straight through. When
+    # it does handle a request it answers 204 itself and never calls downstream, so
+    # the configured path must be one no host route uses.
+    #
+    # Pick ONE CSP mechanism: this endpoint OR the JS securitypolicyviolation
+    # listener (config.capture_csp_violations). Enabling both, with report-uri
+    # aimed here, double-counts every violation.
+    class ReportingEndpointMiddleware
+      MAX_BODY_BYTES = 64_000
+      MAX_REPORTS    = 50
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        config = Dispatch::Rails.configuration
+        return @app.call(env) unless handles?(config, env)
+
+        # @app.call above is deliberately OUTSIDE any rescue — a normal request's
+        # exceptions must propagate to Rails' exception handling, never be
+        # swallowed here. Only the report-handling path is rescued.
+        handle_report(env)
+      end
+
+      private
+
+      def handle_report(env)
+        capture_reports(env)
+        no_content
+      rescue StandardError => e
+        # A report endpoint must never error the browser's beacon — always 204.
+        warn "[dispatch-rails] reporting endpoint failed: #{e.class}: #{e.message}"
+        no_content
+      end
+
+      # A FRESH Rack triple per call — downstream middleware mutates the array and
+      # headers, so a shared/frozen response would raise or corrupt across requests.
+      def no_content
+        [204, { "Content-Type" => "text/plain" }, []]
+      end
+
+      def handles?(config, env)
+        config.browser_reports_enabled? &&
+          env["REQUEST_METHOD"] == "POST" &&
+          path_match?(config, env["PATH_INFO"])
+      end
+
+      def path_match?(config, path)
+        target = config.reporting_endpoint_path.to_s
+        return false if target.empty?
+
+        path == target || path == "#{target}/"
+      end
+
+      def capture_reports(env)
+        raw = read_body(env)
+        return if raw.empty?
+
+        parse_reports(content_type(env), raw).first(MAX_REPORTS).each do |report|
+          capture_one(report, env)
+        end
+      end
+
+      def capture_one(report, env)
+        type = report[:type].to_s
+        body = report[:body].is_a?(Hash) ? report[:body] : {}
+        csp?(type) ? capture_csp(body, env) : capture_generic(type, body, env)
+      end
+
+      def capture_csp(body, env)
+        fields = csp_fields(body)
+        directive = fields[:effective_directive] || fields[:violated_directive] || "policy"
+        blocked = fields[:blocked_uri] || "inline"
+        Reporter.capture(
+          CspViolation.new("#{directive} blocked #{blocked}"),
+          handled: true, env: env,
+          # report-only disposition is monitoring, not a live block — keep it quieter.
+          level: fields[:disposition].to_s == "report" ? "info" : "warning",
+          context: { tags: { csp: "true", report_type: "csp-violation" }.merge(fields) }
+        )
+      end
+
+      def capture_generic(type, body, env)
+        label = type.empty? ? "unknown" : type
+        Reporter.capture(
+          BrowserReport.new("Browser report: #{label}"),
+          handled: true, env: env, level: "info",
+          context: { tags: { report_type: label }.merge(stringify(body)) }
+        )
+      end
+
+      def csp?(type)
+        type == "csp-violation" || type == "csp"
+      end
+
+      # Normalize the two CSP spellings: report-uri's hyphen-case
+      # (blocked-uri/document-uri) and the Reporting API's camelCase, which also
+      # renamed the *-uri fields to *URL.
+      def csp_fields(body)
+        {
+          blocked_uri:         body["blocked-uri"] || body["blockedURI"] || body["blockedURL"],
+          document_uri:        body["document-uri"] || body["documentURI"] || body["documentURL"],
+          violated_directive:  body["violated-directive"] || body["violatedDirective"],
+          effective_directive: body["effective-directive"] || body["effectiveDirective"],
+          source_file:         body["source-file"] || body["sourceFile"],
+          line_number:         body["line-number"] || body["lineNumber"],
+          column_number:       body["column-number"] || body["columnNumber"],
+          disposition:         body["disposition"]
+        }.compact
+      end
+
+      # Legacy report-uri sends a single { "csp-report": {...} } object; the
+      # Reporting API sends an array of { "type", "body" } under reports+json.
+      def parse_reports(content_type, raw)
+        data = JSON.parse(raw)
+        if content_type.include?("reports+json") || data.is_a?(Array)
+          Array(data).map { |r| { type: r["type"], body: r["body"] } }
+        elsif data.is_a?(Hash) && data.key?("csp-report")
+          [{ type: "csp-violation", body: data["csp-report"] }]
+        elsif data.is_a?(Hash)
+          [{ type: "csp-violation", body: data }]
+        else
+          []
+        end
+      rescue JSON::ParserError
+        []
+      end
+
+      def read_body(env)
+        input = env["rack.input"]
+        return "" unless input
+
+        raw = input.read(MAX_BODY_BYTES).to_s
+        input.rewind if input.respond_to?(:rewind)
+        raw
+      rescue StandardError
+        ""
+      end
+
+      def content_type(env)
+        (env["CONTENT_TYPE"] || env["HTTP_CONTENT_TYPE"]).to_s
+      end
+
+      def stringify(hash)
+        return {} unless hash.is_a?(Hash)
+
+        hash.each_with_object({}) { |(k, v), out| out[k.to_s] = v }
+      end
+    end
+  end
+end

data/lib/dispatch/rails/version.rb

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

data/lib/dispatch-rails.rb

@@ -4,6 +4,7 @@ require "dispatch/rails/event_builder"
 require "dispatch/rails/transport"
 require "dispatch/rails/reporter"
 require "dispatch/rails/middleware"
+require "dispatch/rails/reporting_endpoint_middleware"
 require "dispatch/rails/response_annotator"
 require "dispatch/rails/heartbeat_aggregator"
 require "dispatch/rails/heartbeat_middleware"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dispatch-rails
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Dispatch Team
@@ -55,6 +55,7 @@ files:
 - lib/dispatch/rails/middleware.rb
 - lib/dispatch/rails/rake_handler.rb
 - lib/dispatch/rails/reporter.rb
+- lib/dispatch/rails/reporting_endpoint_middleware.rb
 - lib/dispatch/rails/response_annotator.rb
 - lib/dispatch/rails/transport.rb
 - lib/dispatch/rails/version.rb