solid_errors-frontend 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b92029d68f265e946100c2e7b55f85f750a840ac9b94d50d4a1af9a17cbb31a1
+  data.tar.gz: 9887401d8ad11b40d3e29fd600fa3b2bd091bd483f3a35291b377e4952ee34d1
+SHA512:
+  metadata.gz: 031c3ab7bde338a19fb2682590e5bdf9194cd7b985a27a40e84306017046127ef1d1a52d3aba7a62ceb470bc197ca8cb988183d5540065a945c4d11b7d33683a
+  data.tar.gz: 7e277694e98ee9bb4182b1a2fb0afd2a59b9b9da4fc174dac1c14795d5c0e217c730bbf320a9bafe0b8d372b6b910cb415d01cd9814dec253b2fcb330ce72beb

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0
+
+First release.
+
+- Captures uncaught JavaScript exceptions, unhandled promise rejections, Stimulus
+  controller errors and Turbo failures in the browser and reports them through
+  `ActiveSupport::ErrorReporter`, so Solid Errors records them alongside
+  server-side errors.
+- Resolves frames of your own assets back through the Propshaft digest and
+  re-emits them as Ruby backtrace lines, so Solid Errors marks them as
+  application code and renders the surrounding source.
+- Normalises messages before reporting, so one recurring bug stays one row rather
+  than splitting across the ids and URLs in its text.
+- Bounded on every axis, since the ingest endpoint is unauthenticated by design:
+  per-IP rate limit, body size, reports per request and per page, message length,
+  frame count, and the generated exception-class registry.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Armand Mégrot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,170 @@
+# solid_errors-frontend
+
+Browser errors in your [Solid Errors](https://github.com/fractaledmind/solid_errors)
+dashboard.
+
+Uncaught JavaScript exceptions, unhandled promise rejections, Stimulus controller
+errors and Turbo failures are captured in the browser, posted to a mounted
+engine, and handed to `ActiveSupport::ErrorReporter` — the same path Solid Errors
+already receives server-side errors on. They arrive as ordinary rows, grouped and
+deduplicated like everything else, with frames pointing at your own source files.
+
+![A JavaScript TypeError in the Solid Errors dashboard, its backtrace resolved to
+the Stimulus controller that raised it, with the failing line
+highlighted](docs/dashboard-error.png)
+
+> A third-party gem. Not affiliated with, or endorsed by, the solid_errors
+> project; it shares the name prefix because that's what it pairs with.
+
+**Requires Rails 8.0+, Propshaft and importmap** — see [Supported
+stack](#supported-stack).
+
+## Why the backtraces are readable
+
+With importmap + Propshaft there is no bundling and no minification, so a line
+number in a served asset matches the source file exactly — no source maps
+required. Frames are resolved back through the Propshaft digest
+(`application-abc12345.js` → `application.js`) and re-emitted in Ruby's backtrace
+shape:
+
+```
+/rails/app/javascript/controllers/map_controller.js:42:in `connect'
+```
+
+`SolidErrors::BacktraceLine` parses those, treats paths under the project root as
+application code, and renders the surrounding source — so a browser error opens
+in the dashboard showing the JavaScript that raised it. Frames that can't be
+resolved (CDN scripts, extensions, inline handlers) pass through verbatim and
+degrade to unparsed text rather than pointing somewhere wrong.
+
+Because the file part of that format can't contain a colon and a trailing
+`:column` breaks the match, columns are dropped from the frame and reported in
+the context instead.
+
+## Install
+
+```ruby
+gem "solid_errors-frontend"
+```
+
+Mount the engine and add the config tag to your layout:
+
+```ruby
+# config/routes.rb
+mount SolidErrors::Frontend::Engine, at: "/frontend_errors"
+```
+
+```erb
+<%# app/views/layouts/application.html.erb, in <head> %>
+<%= frontend_errors_tag %>
+```
+
+Start the reporter before your own code, so it's listening when that code runs:
+
+```js
+// app/javascript/application.js
+import { start } from "solid_errors_frontend"
+start()
+```
+
+And hook Stimulus, which otherwise swallows every controller error into
+`console.error`:
+
+```js
+// app/javascript/controllers/application.js
+import { installStimulusErrorHandler } from "solid_errors_frontend"
+
+const application = Application.start()
+installStimulusErrorHandler(application)
+```
+
+## Supported stack
+
+| | |
+|---|---|
+| **Rails 8.0+** | The ingest controller scopes its rate limit with `rate_limit(name:)`, which arrived in 8.0. |
+| **Propshaft** | Required to resolve frames back to source. Under Sprockets or a bundler (esbuild, vite) everything still works — errors are reported, grouped and deduplicated — but every frame stays verbatim, because a minified line number doesn't correspond to a source line. |
+| **importmap** | The JavaScript ships through the asset pipeline; there is no npm package. A bundled app has to reference the file directly rather than importing the bare specifier. |
+
+Solid Errors itself is *not* a runtime dependency. Reports go through
+`Rails.error`, so this works with any `ErrorReporter` subscriber — or none at
+all, which is what makes it safe in development and test where Solid Errors is
+often not installed. Everything below about grouping and fingerprints describes
+Solid Errors specifically, because that is what it's built for.
+
+## Configuration
+
+```ruby
+# config/initializers/solid_errors_frontend.rb
+SolidErrors::Frontend.context = -> {
+  { user_id: Current.user&.id }
+}
+```
+
+| Option | Default | |
+|---|---|---|
+| `base_controller_class` | `"::ActionController::Base"` | Superclass of the ingest controller. Deliberately not the host's `ApplicationController`: the endpoint has to work without a session so errors on sign-in pages are captured. |
+| `context` | `-> { {} }` | Lambda `instance_exec`'d in the controller; returns extra flat context. Has access to `request`, `cookies`, … |
+| `allowed_context_keys` | url, referrer, viewport, identifier, frame_id, method, status | Client-supplied context keys to keep. Strings or symbols. |
+| `rate_limit_to` / `rate_limit_within` | `30` / `1.minute` | Per-IP limit on the endpoint. |
+| `max_body_bytes` | `64.kilobytes` | Larger requests get a 413. |
+| `max_reports_per_request` | `20` | |
+| `max_reports_per_page` | `10` | Browser-side budget, reset on each Turbo visit. |
+| `max_message_length` | `500` | |
+| `max_frames` | `30` | |
+| `message_filters` | uuids, urls, digests | Applied before reporting — see below. |
+| `log_reports` | `nil` (on outside production) | Log every report, which is how you see the pipeline work in an environment with no subscriber. |
+
+### Context
+
+Two sources are merged. `SolidErrors::Frontend.context` is server-derived and
+unrestricted — put identity there. Anything the browser sends is filtered through
+`allowed_context_keys`, since the endpoint is unauthenticated; extend it with
+whatever your own instrumentation reports:
+
+```ruby
+SolidErrors::Frontend.allowed_context_keys += %w[activity_id]
+```
+
+Values are coerced to short scalars whatever the list says, and **server-derived
+context is merged last**, so a client can never overwrite a key the server
+resolved for it — including one you add to the allowlist yourself.
+
+### Message normalisation
+
+Solid Errors fingerprints on `exception_class + message + severity + source`, so
+an id or URL inside the message would split one recurring bug across an unbounded
+number of rows. `message_filters` collapses those before reporting.
+
+### What arrives in the dashboard
+
+- **Exception class** — `JS::TypeError`, `JS::UnhandledRejection`, … built per
+  JavaScript error name so the grouping stays legible. Names are allowlisted and
+  the registry is capped, since the value comes from the client.
+- **Source** — `javascript.window`, `javascript.promise`, `javascript.stimulus`,
+  `javascript.turbo`, so capture sites don't group together.
+- **Severity** — `:error`, except Turbo failures which are `:warning`.
+- **Context** — url, referrer, viewport, column, user agent, plus whatever
+  `SolidErrors::Frontend.context` adds and a small allowlist of per-source detail
+  (Stimulus identifier, Turbo frame id).
+
+Which puts them in the same list as everything else, rather than a place you have
+to remember to check:
+
+![The Solid Errors index listing a server-side NoMethodError, a
+JS::TurboFrameMissing and a JS::TypeError together](docs/dashboard-index.png)
+
+## Endpoint exposure
+
+`POST` to the mounted path is unauthenticated and CSRF-exempt: errors on the
+sign-in page are worth having, and `navigator.sendBeacon` — the only transport
+that survives a closing page — can't set a CSRF header. It is therefore bounded
+on every axis: per-IP rate limit, body size, reports per request, message length,
+and the generated exception-class registry.
+
+One caveat on the rate limit: it counts through `Rails.cache#increment`, so it is
+only as real as the configured store. Against a `:null_store` it counts nothing
+and the limit never trips. The other bounds hold regardless.
+
+If the noise ever outweighs the coverage, set `base_controller_class` to a
+controller that requires a session and accept losing pre-login errors.

data/app/assets/javascripts/solid_errors_frontend.js

@@ -0,0 +1,222 @@
+// Browser-side error reporter.
+//
+// Captures uncaught exceptions, unhandled promise rejections, Stimulus
+// controller errors and Turbo failures, and posts them to the mounted engine,
+// which reports them through Rails.error.
+//
+// Configuration comes from <meta name="solid-errors-frontend"> (see TagsHelper).
+
+const DEFAULTS = {
+  endpoint: "/frontend_errors",
+  maxReports: 10,
+  maxMessageLength: 500,
+  maxFrames: 30,
+  flushDelay: 1000
+}
+
+// Messages that carry no actionable information. "Script error." is what
+// browsers report for exceptions thrown by cross-origin scripts, and the
+// ResizeObserver warnings are fired by layout timing rather than by a bug.
+const IGNORED_MESSAGES = [
+  /^Script error\.?$/,
+  /^ResizeObserver loop/
+]
+
+const EXTENSION_SCHEME = /^(chrome|moz|safari-web|safari)-extension:\/\//
+
+const config = { ...DEFAULTS }
+const queue = []
+const seen = new Set()
+
+let started = false
+let reported = 0
+let reporting = false
+let flushTimer = null
+
+function readConfig() {
+  const meta = document.querySelector("meta[name='solid-errors-frontend']")
+  if (!meta) return
+
+  try {
+    Object.assign(config, JSON.parse(meta.content))
+  } catch {
+    // A malformed tag shouldn't disable reporting; the defaults still work.
+  }
+}
+
+function truncate(value, length) {
+  const text = String(value ?? "")
+  return text.length > length ? `${text.slice(0, length - 1)}…` : text
+}
+
+// Cross-origin and extension frames tell us nothing about our own code, and
+// extensions in particular generate a lot of noise on other people's pages.
+function isNoise(message, stack) {
+  if (IGNORED_MESSAGES.some((pattern) => pattern.test(message))) return true
+  if (!stack) return false
+
+  const frames = stack.split("\n").filter((line) => /https?:|:\d+:\d+/.test(line))
+  return frames.length > 0 && frames.every((line) => EXTENSION_SCHEME.test(line.trim().replace(/^at\s+/, "")))
+}
+
+function pageContext() {
+  return {
+    url: window.location.href,
+    referrer: document.referrer || undefined,
+    viewport: `${window.innerWidth}x${window.innerHeight}`
+  }
+}
+
+export function report({ name, message, stack, source, context = {} }) {
+  // A failure inside the reporter must never re-enter it.
+  if (reporting || !started) return
+
+  try {
+    reporting = true
+
+    const text = truncate(message, config.maxMessageLength)
+    if (!text && !name) return
+    if (isNoise(text, stack)) return
+
+    const key = `${name}|${text}|${(stack || "").split("\n")[1] || ""}`
+    if (seen.has(key)) return
+    if (reported >= config.maxReports) return
+
+    seen.add(key)
+    reported += 1
+
+    queue.push({
+      name: name || "Error",
+      message: text,
+      stack: stack ? stack.split("\n").slice(0, config.maxFrames + 1).join("\n") : undefined,
+      source,
+      context: { ...pageContext(), ...context }
+    })
+
+    scheduleFlush()
+  } catch {
+    // Reporting is best-effort.
+  } finally {
+    reporting = false
+  }
+}
+
+function scheduleFlush() {
+  if (flushTimer) return
+  flushTimer = setTimeout(() => flush(), config.flushDelay)
+}
+
+function flush({ beacon = false } = {}) {
+  if (flushTimer) {
+    clearTimeout(flushTimer)
+    flushTimer = null
+  }
+  if (queue.length === 0) return
+
+  const body = JSON.stringify({ reports: queue.splice(0, queue.length) })
+
+  // On pagehide the document may be torn down before fetch resolves, so use
+  // sendBeacon there; it can't set headers, which is why the endpoint is
+  // CSRF-exempt.
+  if (beacon && navigator.sendBeacon) {
+    navigator.sendBeacon(config.endpoint, new Blob([body], { type: "application/json" }))
+    return
+  }
+
+  fetch(config.endpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body,
+    keepalive: true,
+    credentials: "same-origin"
+  }).catch(() => {
+    // Dropping a report is preferable to an unhandled rejection here, which
+    // would come straight back through our own rejection handler.
+  })
+}
+
+function errorFrom(value) {
+  if (value instanceof Error) {
+    return { name: value.name, message: value.message, stack: value.stack }
+  }
+  return { name: "Error", message: String(value) }
+}
+
+function onError(event) {
+  if (event.error) {
+    report({ ...errorFrom(event.error), source: "window" })
+  } else if (event.message) {
+    // Cross-origin scripts give an ErrorEvent with no Error object. The
+    // location is still worth keeping, formatted so the server can resolve it.
+    report({
+      name: "Error",
+      message: event.message,
+      stack: event.filename ? `    at ${event.filename}:${event.lineno || 0}:${event.colno || 0}` : undefined,
+      source: "window"
+    })
+  }
+}
+
+function onUnhandledRejection(event) {
+  const { name, message, stack } = errorFrom(event.reason)
+  report({ name: name === "Error" ? "UnhandledRejection" : name, message, stack, source: "promise" })
+}
+
+function onTurboFetchError(event) {
+  const request = event.detail?.request
+  report({
+    name: "TurboFetchRequestError",
+    message: `${request?.method || "GET"} ${request?.url || "request"} failed`,
+    source: "turbo",
+    context: { method: request?.method, url: request?.url?.toString() }
+  })
+}
+
+function onTurboFrameMissing(event) {
+  report({
+    name: "TurboFrameMissing",
+    message: `Response missing turbo-frame #${event.target?.id || "unknown"}`,
+    source: "turbo",
+    context: { frame_id: event.target?.id, status: event.detail?.response?.status }
+  })
+}
+
+// Turbo Drive keeps the document alive across navigations, so a per-page-load
+// budget has to be reset on visits rather than on load.
+function onTurboLoad() {
+  reported = 0
+}
+
+export function start() {
+  if (started) return
+  started = true
+
+  readConfig()
+
+  window.addEventListener("error", onError)
+  window.addEventListener("unhandledrejection", onUnhandledRejection)
+  document.addEventListener("turbo:fetch-request-error", onTurboFetchError)
+  document.addEventListener("turbo:frame-missing", onTurboFrameMissing)
+  document.addEventListener("turbo:load", onTurboLoad)
+
+  window.addEventListener("pagehide", () => flush({ beacon: true }))
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "hidden") flush({ beacon: true })
+  })
+}
+
+// Stimulus routes every controller lifecycle and action error through
+// handleError, which only logs by default — so without this the majority of
+// application errors never surface.
+export function installStimulusErrorHandler(application) {
+  const original = application.handleError.bind(application)
+
+  application.handleError = (error, message, detail) => {
+    report({
+      ...errorFrom(error),
+      source: "stimulus",
+      context: { identifier: detail?.identifier }
+    })
+    original(error, message, detail)
+  }
+}

data/app/controllers/solid_errors/frontend/reports_controller.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module SolidErrors::Frontend
+  class ReportsController < SolidErrors::Frontend.base_controller_class.constantize
+    # navigator.sendBeacon can't set an X-CSRF-Token header, and the beacon path is
+    # the one that survives a page being closed — which is exactly when we most
+    # want the queued errors. See the class comment below for what guards this
+    # instead.
+    skip_forgery_protection
+
+    # The endpoint is deliberately reachable without a session, so that errors on
+    # the sign-in and sign-up pages are captured too. That makes it publicly
+    # writable, so it's bounded on every axis: requests per IP here, body size and
+    # report count in #create, message length in MessageNormalizer, and the
+    # generated exception-class registry in SolidErrors::Frontend.error_class_for.
+    #
+    # The per-IP limit leans on Rails.cache#increment, so it is only as real as the
+    # configured store — with a :null_store it counts nothing. The other bounds
+    # hold regardless.
+    rate_limit to: SolidErrors::Frontend.rate_limit_to,
+               within: SolidErrors::Frontend.rate_limit_within,
+               name: "solid_errors_frontend"
+
+    def create
+      return head(:content_too_large) if request.content_length.to_i > SolidErrors::Frontend.max_body_bytes
+
+      source_mapper = SourceMapper.new(host: request.host)
+
+      Payload.parse(request.body.read).each do |report|
+        Reporter.new(report, context: report_context, source_mapper: source_mapper).call
+      end
+
+      head :no_content
+    end
+
+    private
+      # No `url` here: the client reports its own `location.href`, which is both
+      # more accurate than a Referer taken at flush time and unaffected by
+      # Referrer-Policy. Deriving one here would only fight it, since server
+      # context takes precedence.
+      def report_context
+        { user_agent: request.user_agent }.merge(host_context).compact
+      end
+
+      # Host-supplied identity/context. Evaluated in the controller so it can read
+      # cookies, headers and whatever else the app needs to resolve a user.
+      def host_context
+        context = instance_exec(&SolidErrors::Frontend.context)
+        context.is_a?(Hash) ? context : {}
+      end
+  end
+end

data/app/helpers/solid_errors/frontend/tags_helper.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module SolidErrors::Frontend
+  module TagsHelper
+    # Configuration for the browser-side reporter, read by
+    # solid_errors_frontend.js. A meta tag rather than an inline script so the
+    # module stays a plain, cacheable asset and nothing has to be exempted from a
+    # CSP.
+    def frontend_errors_tag(**overrides)
+      config = {
+        endpoint: solid_errors_frontend.reports_path,
+        maxReports: SolidErrors::Frontend.max_reports_per_page,
+        maxMessageLength: SolidErrors::Frontend.max_message_length,
+        maxFrames: SolidErrors::Frontend.max_frames
+      }.merge(overrides)
+
+      tag.meta(name: "solid-errors-frontend", content: config.to_json)
+    end
+  end
+end

data/config/importmap.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+pin "solid_errors_frontend", to: "solid_errors_frontend.js"

data/config/routes.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+SolidErrors::Frontend::Engine.routes.draw do
+  post "/" => "reports#create", as: :reports
+end

data/lib/solid_errors/frontend/backtrace_formatter.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module SolidErrors::Frontend
+  # Renders browser frames as Ruby backtrace lines.
+  #
+  # Error backends parse backtraces with a Ruby-shaped regex — roughly
+  #
+  #     /^((?:[a-zA-Z]:)?[^:]+):(\d+)(?::in [`']([^']+)')?$/
+  #
+  # so a frame written as "/app/javascript/foo.js:42:in `connect'" is understood,
+  # linked to its source and (when the path is under the project root) treated as
+  # application code. Two constraints follow from that regex: the file part can't
+  # contain a colon, and a trailing ":column" makes the whole line fail to match —
+  # hence columns are dropped here and carried in the report context instead.
+  #
+  # Frames we can't resolve to a source file are emitted verbatim; backends fall
+  # back to showing the unparsed line, so nothing is lost.
+  class BacktraceFormatter
+    DEFAULT_METHOD = "<anonymous>"
+
+    def initialize(source_mapper)
+      @source_mapper = source_mapper
+    end
+
+    # @param frames [Array<StackParser::Frame>]
+    # @return [Array<String>]
+    def call(frames)
+      frames.filter_map { |frame| format_frame(frame) }
+    end
+
+    private
+      def format_frame(frame)
+        return frame.raw if frame.url.nil? || frame.line.nil?
+
+        path = @source_mapper.resolve(frame.url)
+        return frame.raw unless path
+
+        "#{path}:#{frame.line}:in `#{frame.function || DEFAULT_METHOD}'"
+      end
+  end
+end

data/lib/solid_errors/frontend/engine.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module SolidErrors::Frontend
+  class Engine < ::Rails::Engine
+    isolate_namespace SolidErrors::Frontend
+
+    # Serve app/assets/javascripts/solid_errors_frontend.js through the host's
+    # asset pipeline. Propshaft and Sprockets both serve it; only Propshaft can
+    # resolve the served URL back to a source file (see SourceMapper).
+    initializer "solid_errors_frontend.assets" do |app|
+      app.config.assets.paths << root.join("app/assets/javascripts") if app.config.respond_to?(:assets)
+    end
+
+    # Importmap::Engine's own "importmap" initializer draws every path in
+    # config.importmap.paths, so ours has to be appended before it runs.
+    initializer "solid_errors_frontend.importmap", before: "importmap" do |app|
+      next unless app.config.respond_to?(:importmap)
+
+      app.config.importmap.paths << root.join("config/importmap.rb")
+      app.config.importmap.cache_sweepers << root.join("app/assets/javascripts")
+    end
+
+    # isolate_namespace keeps engine helpers out of the host's views, but
+    # frontend_errors_tag has to be callable from the host layout.
+    initializer "solid_errors_frontend.helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include SolidErrors::Frontend::TagsHelper
+      end
+    end
+  end
+end

data/lib/solid_errors/frontend/message_normalizer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SolidErrors::Frontend
+  # Collapses the parts of a message that vary between occurrences of the same bug.
+  #
+  # Error backends typically fingerprint on the message (Solid Errors hashes
+  # exception class + message + severity + source), so an id, a URL or a digest
+  # inside the text would split one recurring bug into an unbounded number of
+  # groups. Normalising first keeps one bug to one row.
+  class MessageNormalizer
+    def self.call(message, filters: SolidErrors::Frontend.message_filters, limit: SolidErrors::Frontend.max_message_length)
+      new(filters: filters, limit: limit).call(message)
+    end
+
+    def initialize(filters: SolidErrors::Frontend.message_filters, limit: SolidErrors::Frontend.max_message_length)
+      @filters = filters
+      @limit = limit
+    end
+
+    def call(message)
+      text = message.to_s.strip.gsub(/\s+/, " ")
+      text = @filters.reduce(text) { |result, (pattern, replacement)| result.gsub(pattern, replacement) }
+      truncate(text)
+    end
+
+    private
+      def truncate(text)
+        return text if text.length <= @limit
+
+        "#{text[0, @limit - 1]}…"
+      end
+  end
+end

data/lib/solid_errors/frontend/payload.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "json"
+
+module SolidErrors::Frontend
+  # Parses the request body into Reports.
+  #
+  # This is the trust boundary: the endpoint is unauthenticated by design (errors
+  # on the sign-in page are worth having), so malformed or hostile input has to
+  # produce an empty list rather than an exception.
+  module Payload
+    def self.parse(body, limit: SolidErrors::Frontend.max_reports_per_request)
+      parsed = JSON.parse(body.to_s)
+      return [] unless parsed.is_a?(Hash)
+
+      reports = parsed["reports"]
+      return [] unless reports.is_a?(Array)
+
+      reports.first(limit).filter_map do |attributes|
+        Report.from(attributes) if attributes.is_a?(Hash)
+      end
+    rescue JSON::ParserError
+      []
+    end
+  end
+end

data/lib/solid_errors/frontend/report.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module SolidErrors::Frontend
+  # One browser error, normalised into everything needed to report it.
+  #
+  # Every field here arrives from the client, so nothing is passed through
+  # untouched: the capture site picks the reported source and severity (rather
+  # than the payload naming them), extra context is allowlisted, and the message
+  # is normalised and truncated.
+  class Report
+    # Capture site => [reported source, severity, handled]. The source ends up in
+    # the fingerprint, so this both labels the report and keeps, say, a Turbo
+    # failure from grouping with an identically-worded uncaught exception.
+    CAPTURE_SITES = {
+      "window" => [ "javascript.window", :error, false ],
+      "promise" => [ "javascript.promise", :error, false ],
+      "stimulus" => [ "javascript.stimulus", :error, false ],
+      "turbo" => [ "javascript.turbo", :warning, true ]
+    }.freeze
+
+    DEFAULT_CAPTURE_SITE = [ "javascript", :error, false ].freeze
+
+    # Values are kept flat and short whatever SolidErrors::Frontend.allowed_context_keys
+    # permits: backends render context as a plain key/value list, and the payload
+    # is unauthenticated.
+    MAX_CONTEXT_VALUE_LENGTH = 200
+
+    attr_reader :name, :message, :stack, :source, :severity, :context
+
+    def self.from(attributes)
+      attributes = attributes.to_h { |key, value| [ key.to_s, value ] }
+
+      # A blank message would be dropped (or worse, raise) by backends that
+      # require one, so fall back to the error name before giving up.
+      message = MessageNormalizer.call(attributes["message"])
+      message = MessageNormalizer.call(attributes["name"]) if message.empty?
+      return nil if message.empty?
+
+      new(
+        name: attributes["name"],
+        message: message,
+        stack: attributes["stack"],
+        capture_site: attributes["source"],
+        context: attributes["context"]
+      )
+    end
+
+    def initialize(name:, message:, stack:, capture_site:, context: nil)
+      @name = name
+      @message = message
+      @stack = stack
+      @source, @severity, @handled = CAPTURE_SITES.fetch(capture_site.to_s, DEFAULT_CAPTURE_SITE)
+      @context = sanitize_context(context)
+    end
+
+    def handled? = @handled
+
+    def error_class = SolidErrors::Frontend.error_class_for(name)
+
+    def frames
+      @frames ||= StackParser.parse(stack)
+    end
+
+    private
+      def sanitize_context(context)
+        return {} unless context.respond_to?(:each_pair)
+
+        # Hosts configure the allowlist with whichever of strings or symbols come
+        # naturally; compare on strings.
+        allowed = SolidErrors::Frontend.allowed_context_keys.map(&:to_s)
+
+        context.each_pair.with_object({}) do |(key, value), result|
+          key = key.to_s
+          next unless allowed.include?(key)
+          next unless scalar?(value)
+
+          result[key.to_sym] = value.is_a?(String) ? value.strip[0, MAX_CONTEXT_VALUE_LENGTH] : value
+        end
+      end
+
+      def scalar?(value)
+        case value
+        when String, Numeric, TrueClass, FalseClass then true
+        else false
+        end
+      end
+  end
+end

data/lib/solid_errors/frontend/reporter.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module SolidErrors::Frontend
+  # Hands a browser error to Rails' error reporter.
+  #
+  # SolidErrors::Subscriber is a plain ErrorSubscriber, so this is the way in:
+  # going to SolidErrors::Error directly would bypass its sanitizer, fingerprint
+  # dedup and occurrence creation. It also means solid_errors need not be loaded
+  # at all — in an environment with no subscriber the report simply goes nowhere,
+  # which is why the gem works in development and test.
+  class Reporter
+    def initialize(report, context: {}, source_mapper: SourceMapper.new)
+      @report = report
+      @context = context
+      @source_mapper = source_mapper
+    end
+
+    def call
+      error = build_error
+      log(error) if SolidErrors::Frontend.log_reports?
+
+      Rails.error.report(
+        error,
+        handled: @report.handled?,
+        severity: @report.severity,
+        source: @report.source,
+        context: context
+      )
+    end
+
+    private
+      def build_error
+        error = @report.error_class.new(@report.message)
+        error.set_backtrace(backtrace)
+        error
+      end
+
+      def backtrace
+        BacktraceFormatter.new(@source_mapper).call(@report.frames)
+      end
+
+      # Server-derived context is merged last, so it always wins: whatever a host
+      # adds to `allowed_context_keys`, a client must never be able to overwrite
+      # the identity we resolved for it.
+      def context
+        top_frame = @report.frames.first
+        @report.context
+          .merge(@context)
+          .merge(column: top_frame&.column)
+          .compact
+      end
+
+      def log(error)
+        Rails.logger.warn do
+          "[solid_errors_frontend] #{error.class.name}: #{error.message} " \
+            "(#{@report.source}) #{error.backtrace&.first}"
+        end
+      end
+  end
+end

data/lib/solid_errors/frontend/source_mapper.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module SolidErrors::Frontend
+  # Resolves the URL of a served asset back to the source file it was built from.
+  #
+  # No source maps are involved and none are needed: with importmap + Propshaft
+  # there is no bundling or minification, so line numbers in the served asset
+  # match the source file exactly. All that has to be undone is the digest
+  # Propshaft splices into the filename (application-abc12345.js).
+  #
+  # Returning an absolute path under Rails.root is what lets an error backend
+  # recognise the frame as application code and show the surrounding source.
+  class SourceMapper
+    MAX_CACHE_SIZE = 500
+
+    def initialize(host: nil)
+      @host = host
+      @cache = {}
+    end
+
+    # @return [String, nil] absolute path of the source file, if it can be found
+    def resolve(url)
+      return nil if url.nil?
+
+      @cache.fetch(url) do
+        path = lookup(url)
+        @cache.clear if @cache.size >= MAX_CACHE_SIZE
+        @cache[url] = path
+      end
+    end
+
+    private
+      def lookup(url)
+        path = asset_path(url)
+        return nil unless path
+
+        logical_path, _digest = Propshaft::Asset.extract_path_and_digest(path)
+        asset = Rails.application.assets.load_path.find(logical_path)
+        asset&.path&.to_s
+      rescue StandardError
+        # Never let stack rewriting take down the report itself.
+        nil
+      end
+
+      # The path under the asset prefix, or nil when the URL isn't one of our
+      # assets (a CDN, an inline script, a browser extension, another origin).
+      def asset_path(url)
+        return nil unless defined?(Propshaft) && defined?(Rails) && Rails.respond_to?(:application)
+
+        uri = URI.parse(url)
+        return nil if uri.host && @host && uri.host != @host
+        return nil unless uri.path&.start_with?(assets_prefix)
+
+        uri.path.delete_prefix(assets_prefix)
+      rescue URI::InvalidURIError
+        nil
+      end
+
+      def assets_prefix
+        @assets_prefix ||= Rails.application.assets.prefix
+      end
+  end
+end

data/lib/solid_errors/frontend/stack_parser.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module SolidErrors::Frontend
+  # Turns a browser stack trace string into structured frames.
+  #
+  # Two dialects have to be handled. V8 (Chrome, Edge, node) prefixes every frame
+  # with "at" and puts the location in parentheses when a function name is known:
+  #
+  #     Error: boom
+  #         at Object.connect (https://host/assets/x-abc123.js:42:15)
+  #         at https://host/assets/x-abc123.js:1:1
+  #         at new Foo (https://host/assets/x-abc123.js:7:9)
+  #         at async load (https://host/assets/x-abc123.js:3:1)
+  #
+  # SpiderMonkey/JavaScriptCore (Firefox, Safari) use "function@location" with no
+  # prefix, and an empty function name for top-level frames:
+  #
+  #     connect@https://host/assets/x-abc123.js:42:15
+  #     @https://host/assets/x-abc123.js:1:1
+  class StackParser
+    Frame = Struct.new(:function, :url, :line, :column, :raw, keyword_init: true)
+
+    # "at fn (url:line:col)" / "at url:line:col". The location group is greedy up
+    # to the final two ":n" pairs so that URLs containing colons still split right.
+    V8 = /\A\s*at\s+(?:(?<function>.+?)\s+\()?(?<url>.+?):(?<line>\d+):(?<column>\d+)\)?\s*\z/
+
+    # "fn@url:line:col"
+    MOZ = /\A\s*(?<function>[^@]*)@(?<url>.+?):(?<line>\d+):(?<column>\d+)\s*\z/
+
+    def self.parse(stack, limit: SolidErrors::Frontend.max_frames)
+      new(stack).parse(limit: limit)
+    end
+
+    def initialize(stack)
+      @stack = stack.to_s
+    end
+
+    def parse(limit: SolidErrors::Frontend.max_frames)
+      frames = []
+
+      @stack.each_line do |raw_line|
+        line = raw_line.strip
+        next if line.empty?
+
+        if (frame = frame_from(line))
+          frames << frame
+        elsif frames.any?
+          # Something we can't decompose but that sits inside the trace, e.g.
+          # Safari's "[native code]". Worth keeping verbatim.
+          frames << Frame.new(raw: line)
+        end
+        # Anything unparseable *before* the first frame is the "Name: message"
+        # header V8 prepends, which we already have as the message.
+
+        break if frames.size >= limit
+      end
+
+      frames
+    end
+
+    private
+      def frame_from(line)
+        match = V8.match(line) || MOZ.match(line)
+        return unless match
+
+        Frame.new(
+          function: normalize_function(match[:function]),
+          url: match[:url],
+          line: match[:line].to_i,
+          column: match[:column].to_i,
+          raw: line.strip
+        )
+      end
+
+      # "new Foo" and "async load" carry a V8 modifier rather than a name we can
+      # show as-is; keep the name and drop the noise.
+      def normalize_function(function)
+        name = function.to_s.strip
+        name = name.delete_prefix("async ").delete_prefix("new ")
+        name.empty? ? nil : name
+      end
+  end
+end

data/lib/solid_errors/frontend/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module SolidErrors
+  module Frontend
+    VERSION = "0.1.0"
+  end
+end

data/lib/solid_errors/frontend.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/core_ext/module/attribute_accessors"
+require "active_support/core_ext/numeric/bytes"
+require "active_support/core_ext/numeric/time"
+
+require "solid_errors/frontend/version"
+
+# Defined here rather than assumed, because solid_errors itself is not a runtime
+# dependency: reports go through ActiveSupport::ErrorReporter, so an app with no
+# subscriber at all still works. When solid_errors *is* loaded it simply reopens
+# this module.
+module SolidErrors
+  module Frontend
+    # Base class for every error reported from the browser. Concrete classes are
+    # built per JavaScript error name by .error_class_for.
+    class BrowserError < StandardError; end
+
+    # JavaScript error names we're willing to turn into a Ruby class name. Anything
+    # else (including anything an attacker could POST) collapses to JS::Error.
+    NAME_PATTERN = /\A[A-Z][A-Za-z0-9_]{0,63}\z/
+
+    # Upper bound on the generated class registry, so a hostile client can't grow it
+    # without limit.
+    MAX_ERROR_CLASSES = 100
+
+    # Controller the ingest endpoint inherits from. Deliberately not the host's
+    # ApplicationController by default: the endpoint must stay reachable without a
+    # session (errors on the sign-in page matter too), and it shouldn't pick up
+    # whatever before_actions the host installs. Identity comes from `context`.
+    mattr_accessor :base_controller_class, default: "::ActionController::Base"
+
+    # Lambda instance_exec'd in the controller, returning a flat hash of extra
+    # context (user id, native flag, ...). It has access to `request`, `cookies`
+    # and anything else the controller exposes. Not subject to
+    # `allowed_context_keys` — that governs client input, this is server-derived.
+    mattr_accessor :context, default: -> { {} }
+
+    # Client-supplied context keys we're willing to store. An allowlist rather than
+    # a denylist because the payload is unauthenticated: add the keys your own
+    # instrumentation sends, and nothing else gets through. Values are still
+    # constrained to short scalars regardless of what's listed here.
+    mattr_accessor :allowed_context_keys, default: %w[url referrer viewport identifier frame_id method status]
+
+    # Per-IP rate limit on the ingest endpoint. Note this relies on Rails.cache
+    # supporting #increment — with a :null_store it silently does nothing.
+    mattr_accessor :rate_limit_to, default: 30
+    mattr_accessor :rate_limit_within, default: 1.minute
+
+    # Hard caps. Everything below is attacker-controlled, and `message` in particular
+    # feeds the error fingerprint Solid Errors computes for the report.
+    mattr_accessor :max_body_bytes, default: 64.kilobytes
+    mattr_accessor :max_reports_per_request, default: 20
+    mattr_accessor :max_message_length, default: 500
+    mattr_accessor :max_frames, default: 30
+
+    # Budget the browser gives itself per page view, so one error in a loop can't
+    # turn into a flood of requests. Reset on each Turbo visit.
+    mattr_accessor :max_reports_per_page, default: 10
+
+    # Substitutions applied to messages before reporting. Solid Errors fingerprints
+    # on the message, so anything that varies per occurrence (ids, urls, digests)
+    # would otherwise split one bug across many groups.
+    mattr_accessor :message_filters, default: [
+      [ /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/i, "<uuid>" ],
+      [ /\bblob:\S+/i, "<blob-url>" ],
+      [ %r{\bhttps?://\S+}i, "<url>" ],
+      [ /\b[0-9a-f]{16,}\b/i, "<hash>" ]
+    ]
+
+    # Whether to log every report. nil means "decide from the environment": on
+    # outside production, where solid_errors is often not installed and the log is
+    # the only way to see the pipeline work.
+    mattr_accessor :log_reports, default: nil
+
+    class << self
+      def log_reports?
+        return log_reports unless log_reports.nil?
+
+        defined?(Rails) && Rails.respond_to?(:env) && !Rails.env.production?
+      end
+
+      # Builds (and memoizes) an exception class whose #name reads "JS::TypeError".
+      # Solid Errors keys its grouping off the exception class name, so this is what
+      # makes browser errors legible next to server-side ones.
+      def error_class_for(js_name)
+        name = NAME_PATTERN.match?(js_name.to_s) ? js_name.to_s : "Error"
+
+        error_classes_lock.synchronize do
+          error_classes[name] ||=
+            if error_classes.size >= MAX_ERROR_CLASSES
+              BrowserError
+            else
+              Class.new(BrowserError) do
+                define_singleton_method(:name) { "JS::#{name}" }
+              end
+            end
+        end
+      end
+
+      def reset_error_classes! # :nodoc: for tests
+        error_classes_lock.synchronize { @error_classes = {} }
+      end
+
+      private
+        def error_classes
+          @error_classes ||= {}
+        end
+
+        def error_classes_lock
+          @error_classes_lock ||= Mutex.new
+        end
+    end
+  end
+end
+
+require "solid_errors/frontend/message_normalizer"
+require "solid_errors/frontend/stack_parser"
+require "solid_errors/frontend/source_mapper"
+require "solid_errors/frontend/backtrace_formatter"
+require "solid_errors/frontend/report"
+require "solid_errors/frontend/payload"
+require "solid_errors/frontend/reporter"
+require "solid_errors/frontend/engine" if defined?(Rails::Engine)

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: solid_errors-frontend
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Armand Mégrot
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+description: Captures uncaught JavaScript exceptions, unhandled promise rejections,
+  Stimulus controller errors and Turbo failures in the browser and reports them through
+  ActiveSupport::ErrorReporter, so Solid Errors records them alongside server-side
+  errors — with frames resolved back to your source files. A third-party companion
+  gem, not affiliated with solid_errors.
+email:
+- armand.megrot@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- app/assets/javascripts/solid_errors_frontend.js
+- app/controllers/solid_errors/frontend/reports_controller.rb
+- app/helpers/solid_errors/frontend/tags_helper.rb
+- config/importmap.rb
+- config/routes.rb
+- lib/solid_errors/frontend.rb
+- lib/solid_errors/frontend/backtrace_formatter.rb
+- lib/solid_errors/frontend/engine.rb
+- lib/solid_errors/frontend/message_normalizer.rb
+- lib/solid_errors/frontend/payload.rb
+- lib/solid_errors/frontend/report.rb
+- lib/solid_errors/frontend/reporter.rb
+- lib/solid_errors/frontend/source_mapper.rb
+- lib/solid_errors/frontend/stack_parser.rb
+- lib/solid_errors/frontend/version.rb
+homepage: https://github.com/armandmgt/solid_errors-frontend
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/armandmgt/solid_errors-frontend
+  changelog_uri: https://github.com/armandmgt/solid_errors-frontend/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/armandmgt/solid_errors-frontend/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Browser errors in your Solid Errors dashboard
+test_files: []