railwatch 1.5.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd59ae7a65fbd673b2069d096802144c04277a08379fa42285d32677ad5502c6
-  data.tar.gz: 49ff48d1ec8340609c23c12a117ae1e381ac938f7fbdfb6aa914b7e33505a25c
+  metadata.gz: 7d52990b8f664355823660082054f5f886d9ec4f3391936984182cf8526141b3
+  data.tar.gz: 39936e0eba72d4be5223c20948e01717be021cccaaf2819ccf58156f86b76b4a
 SHA512:
-  metadata.gz: 9c45c3639f2787b16b9104afed286ff712bfb63028e13fd83eda44323544ddb9a156c60566287d5465d6daaeffb46b4a8379addb8a51ebf90ab178f9c17a41d4
-  data.tar.gz: 31fe3a1492400bf823ef7dbd04ee22a45edda63349168032b93a3f8e429525cf9cb205b15b96eb6238819a6386916457a75ed3f4de52164227c39e39c8a1a576
+  metadata.gz: e3eda104f83588f1cc3c9c12670e9fc335378aa2cd0413e23a811faff4012513b36c0324c0e8cf6ebaae7c0062a5eb537d647a34482c04cf4b2e3fc7c1955ebc
+  data.tar.gz: 14f360b2772980266c9fd821e5abd8120af7015fa64d59fb29b21ab8e46ab05d070e5de54fc2d9f34c5fa3b99f3de88ac57d2f85fde1f78045986ce3b1c9a83c

data/CHANGELOG.md

@@ -6,6 +6,30 @@
      filled in by the release commit, which is also the only commit that
      touches lib/railwatch/version.rb and Gemfile.lock. See CONTRIBUTING.md. -->
 
+## 1.6.0 (2026-10-29)
+
+- An IPv6 address in an exception message is masked like an IPv4 one, so
+  "scrape trap followed from 2607:fb90:..." groups with "...from
+  40.77.167.14" instead of opening an issue per address. Full and
+  `::`-compressed forms are both covered. A clock time (`12:30:45`) and a
+  constant path (`Foo::Bar`) are left alone.
+- A browser error in a content-hashed bundle (`vite/assets/dist-DedfDSJv.js`)
+  is fingerprinted on the name without the hash (`vite/assets/dist.js`)
+  and without the line, so the same error no longer opens a new issue
+  every deploy. In a minified bundle the line moves with any change
+  before it. The stored frames keep the real file and line.
+- The browser client ignores "Script error." by default. It is all a
+  browser reports for an error in a cross-origin script, with no stack.
+- A file `ActionDispatch::Static` serves from `public/` (a 2xx or 304 for
+  a GET or HEAD no route matched) is no longer recorded as a `GET
+  unmatched` request, nor counted in its session. In rebulk-system that
+  was 3,168 of 36,131 requests a day and about 23 journey rows per page
+  load. Unmatched 404s are still recorded. Routed requests never touch
+  the filesystem for this.
+- `startRailwatch()` does nothing when there is no `window`, so an
+  Inertia SSR entrypoint that calls it at its top level no longer crashes
+  with "document is not defined".
+
 ## 1.5.0 (2026-10-28)
 
 - The browser session is one per browser, shared by every tab, as in GA4

data/app/controllers/railwatch/beacon_controller.rb

@@ -226,8 +226,9 @@ module Railwatch
       message = safe_string(error["message"], MAX_ERROR_MESSAGE)
       frames = Backtrace.js_frames(safe_string(error["stack"], MAX_ERROR_STACK), origin: origin)
       top = Subscribers::Exceptions.top_frame(frames)
+      file, line = Backtrace.js_fingerprint_location(top)
       parts = Subscribers::Exceptions.cap_fingerprint(
-        [ name, top[:file], top[:line], Subscribers::Exceptions.normalize_message(message) ])
+        [ name, file, line, Subscribers::Exceptions.normalize_message(message) ])
       Railwatch.record(:exception,
         group: Record.group_hash(*parts),
         timestamp: safe_float(error["at"]).positive? ? safe_float(error["at"]) / 1000.0 : nil,

data/docs/configuration.md

@@ -755,7 +755,8 @@ running in:
 ```ts
 startRailwatch({
   // Messages never worth an issue, added to the defaults (both
-  // "ResizeObserver loop ..." messages). Strings match anywhere in the
+  // "ResizeObserver loop ..." messages, and the bare "Script error." a
+  // browser gives for a cross-origin script). Strings match anywhere in the
   // message; regexes are tested against it.
   ignoreErrors: [/Failed to fetch dynamically imported module/],
   // Scripts whose failures are not this app's, matched against the top
@@ -781,6 +782,10 @@ does the same thing. See
 [`docs/replacing-sentry.md`](replacing-sentry.md) for what is and is not
 captured versus `@sentry/react`.
 
+The client is safe to import from an SSR bundle: nothing in it touches
+the DOM at import time, and `startRailwatch()` returns without doing
+anything when there is no `window`.
+
 SSR timing needs no configuration. `Railwatch::Patches::Inertia` prepends
 `InertiaRails::Renderer#ssr_render` whenever `inertia_rails` SSR is
 enabled. The resulting `ssr_ms` lands on the `request` record's

data/docs/records.md

@@ -72,7 +72,10 @@ whether child records ship, not whether an error is visible.
 ### `request`
 
 Built by the outermost Rack middleware in
-`lib/railwatch/middleware/request.rb`. That middleware also owns the
+`lib/railwatch/middleware/request.rb`. A file `ActionDispatch::Static`
+served from `public/` (a GET or HEAD no route matched, answered 2xx or
+304, whose path names a file there or its precompressed `.br`/`.gz`) is not recorded. An unmatched request
+for anything else, a 404 included, is. That middleware also owns the
 `middleware_before`/`action`/`render`/`middleware_after` stage
 boundaries. The `action`/`render` boundaries come from
 `start_processing.action_controller` and `render_template.action_view` in
@@ -334,8 +337,9 @@ its own `exceptions` sample rate rolled once per execution. See
 
 The default fingerprint normalizes the message before hashing it, so one
 issue doesn't shatter into thousands. URLs, email addresses, UUIDs, ISO
-timestamps, IPv4 addresses, quoted strings, hex runs of six characters or
-more, and plain integers all become `?`. Whitespace collapses, and the
+timestamps, IPv4 and IPv6 addresses (lower-case hex, full or compressed
+with `::`), quoted strings, hex runs of six characters or more, and plain
+integers all become `?`. Whitespace collapses, and the
 result is cut at 200 chars. For classes whose message is mostly the data
 that varied, only the message *prefix* is kept. The prefix runs up to the
 first `:` for `ActiveRecord::RecordNotFound`, `ActiveRecord::RecordInvalid`,
@@ -393,9 +397,16 @@ line with no location on it is dropped:
 | `in_app` | True when the script came from the app's own origin and is not under `node_modules/` or `vendor/`. |
 
 No source snippets: the file is on the client, not on the server. Frames
-are fingerprinted exactly like Ruby ones: class, top in-app frame, and
-the normalized message. So browser errors group, split, merge, resolve,
-and regress through the same Issue machinery.
+are fingerprinted like Ruby ones: class, top in-app frame, and the
+normalized message. So browser errors group, split, merge, resolve, and
+regress through the same Issue machinery. One difference: when the top
+frame's file name carries a bundler's content hash (`dist-DedfDSJv.js`,
+`main.3f2a1b9c.js`, `app-5XDGVJ2T.mjs`; eight or more characters with a
+digit, or mixed case that does not read as camelCase words, so
+`checkout-PaymentForm.js` keeps its name), the fingerprint uses the name without the hash
+(`dist.js`) and no line. Both change on every deploy of a minified
+bundle, so keeping them would open a new issue each release. The frame
+itself keeps the real file and line.
 
 `context` carries a `browser` key with the page `url`, the Inertia
 `component`, the `visit` the error happened in if any, the browser

data/docs/replacing-sentry.md

@@ -421,7 +421,7 @@ startRailwatch({
 | `Sentry.init({ dsn })` | `startRailwatch()`. There is no DSN: the beacon posts to the app's own origin and the *server* decides whether to record it (`c.beacon_enabled`, and whether Railwatch is enabled). The gate you already have on whether `startRailwatch()` runs at all is the only gate. |
 | `release` | Automatic. The record is stamped with `c.deploy`, the same release the server records carry, so a browser issue and a server issue from one deploy line up without a matching pair of settings to get wrong. |
 | `environment` | Automatic — the ingest token identifies the environment. |
-| `ignoreErrors` | `startRailwatch({ ignoreErrors })`. Strings match anywhere in the message; regexes are tested against it. Both `ResizeObserver` messages are ignored by default. |
+| `ignoreErrors` | `startRailwatch({ ignoreErrors })`. Strings match anywhere in the message; regexes are tested against it. Both `ResizeObserver` messages and the opaque cross-origin `Script error.` are ignored by default. |
 | `denyUrls` | `startRailwatch({ denyUrls })`, matched against the top stack frame's URL. `/extensions\//i`, `/^chrome:\/\//i`, and `/^moz-extension:\/\//i` are denied by default, **and** any frame from an origin that isn't the app's own is dropped — extensions, injected widgets, tag managers. |
 | `Sentry.setUser` | Server-side. The beacon is a same-origin POST carrying the session cookie, so the server resolves the user the same way it does for a request (`Railwatch.user`) when `Current.user` or Warden is set by middleware; an app that authenticates in a `before_action` gives Railwatch the same lookup with `c.beacon_user { \|request\| ... }`. Nothing the browser sends names the user, so it cannot be forged. |
 | `Sentry.setTag("org", …)` | `startRailwatch({ tenant })`, and `Railwatch.context(...)` for everything else. |

data/lib/generators/railwatch/install/templates/railwatch.ts

@@ -84,11 +84,14 @@ export interface RailwatchOptions {
 }
 
 // Browser noise that is never actionable: ResizeObserver fires from benign
-// layout thrash and the spec says to ignore it, and the extension URLs are
-// third-party code running in someone's browser that this app cannot fix.
-const DEFAULT_IGNORE_ERRORS = [
+// layout thrash and the spec says to ignore it, "Script error." is all a
+// browser says about an error in a cross-origin script (no stack, no file,
+// no line), and the extension URLs are third-party code running in
+// someone's browser that this app cannot fix.
+const DEFAULT_IGNORE_ERRORS: (string | RegExp)[] = [
   "ResizeObserver loop limit exceeded",
   "ResizeObserver loop completed with undelivered notifications",
+  /^Script error\.?$/,
 ]
 const DEFAULT_DENY_URLS = [
   /extensions\//i,
@@ -982,7 +985,12 @@ function finalize() {
   flush(true)
 }
 
+// A no-op under server-side rendering: the Inertia SSR server runs the same
+// entrypoint, with no window to measure and nothing to send a beacon from.
+// Nothing above touches the DOM until this is called, so importing the
+// module is safe there too.
 export function startRailwatch(options: RailwatchOptions = {}) {
+  if (typeof window === "undefined") return
   ignoreErrors = [...DEFAULT_IGNORE_ERRORS, ...(options.ignoreErrors ?? [])]
   denyUrls = [...DEFAULT_DENY_URLS, ...(options.denyUrls ?? [])]
   tenantOf = options.tenant

data/lib/railwatch/backtrace.rb

@@ -110,6 +110,41 @@ module Railwatch
 
     MAX_JS_FRAMES = 50
 
+    # A bundler's content hash in a built file's name: Vite and Rollup's
+    # "dist-DedfDSJv.js" (base64url, so it can hold a "-" of its own:
+    # "dist-CMHaG-3i.js"), esbuild's "app-5XDGVJ2T.js", webpack's
+    # "main.3f2a1b9c.js". The name is greedy, so in "yard-canvas-BwMeIV6a.js"
+    # only the last segment that can be a hash is one.
+    JS_CONTENT_HASH = /\A(?<name>.+)[-.](?<hash>[A-Za-z0-9_-]{8,64})(?<ext>\.[mc]?js)\z/
+
+    # Where a browser error is filed for grouping. A content hash changes
+    # every deploy the bundle changes, so it is taken out of the file name,
+    # and so is the line: in a minified bundle the line is wherever the
+    # minifier wrapped (Vite writes the whole app on a line or two) and
+    # shifts with any change before it, which is why Sentry leaves the line
+    # out of a minified frame it has no source map for. The stored frames
+    # keep the real file and line; this is for the fingerprint alone.
+    def js_fingerprint_location(frame)
+      file = frame[:file]
+      match = file && JS_CONTENT_HASH.match(file)
+      return [ file, frame[:line] ] unless match && content_hash?(match[:hash])
+
+      [ "#{match[:name]}#{match[:ext]}", nil ]
+    end
+
+    # A word is not a hash: one has a digit, or mixes cases in a way no
+    # camelCase or PascalCase name does ("DedfDSJv"). So the "timeline" in
+    # "order-timeline.js" and the "PaymentForm" in "checkout-PaymentForm.js"
+    # stay part of the name. A hash that happens to read like words (about
+    # 1 in 100 of eight letters with no digit) is kept too, which costs that
+    # deploy a split issue, never a wrong merge.
+    CAMEL_WORDS = /\A[A-Za-z][a-z]+(?:[A-Z][a-z]{2,})+\z/
+
+    def content_hash?(segment)
+      segment.match?(/\d/) ||
+        (segment.match?(/[a-z]/) && segment.match?(/[A-Z]/) && !segment.match?(CAMEL_WORDS))
+    end
+
     # A browser stack, exactly as the engine wrote it, in the same frame
     # shape as a Ruby backtrace. `origin` is the app's own scheme and host: a
     # script served from it is the app's own, so its file is stored relative

data/lib/railwatch/middleware/request.rb

@@ -145,6 +145,8 @@ module Railwatch
       end
 
       def finish(env, exe, status, headers)
+        return Railwatch.discard_execution if static_file?(env, status)
+
         exe.finish_stages
         # Resolved here, once, for both the request record and the session
         # key below (the start_processing subscriber ran before the app's
@@ -165,6 +167,35 @@ module Railwatch
         nil
       end
 
+      # A file ActionDispatch::Static served from public/: a bundle, a
+      # stylesheet, a favicon. This middleware sits in front of Static, so
+      # without this every one of them is a "GET unmatched" request record
+      # -- about 23 per page load, a tenth of rebulk-system's requests --
+      # and a row in the session's journey. Only a success or a 304 is
+      # skipped: an unmatched 404 is a probe the security tools read.
+      #
+      # Static's 304 is a bare [304, {}, []], so the response cannot say a
+      # file answered it. The path can: it names a file under public/,
+      # looked up the way Static looks (unescaped, cleaned, then with
+      # ".html" or "/index.html", or only its precompressed ".br" or ".gz",
+      # which Static serves in its place). Every check before that one is an
+      # env or integer read, so a routed request never touches the
+      # filesystem.
+      def static_file?(env, status)
+        return false if env["railwatch.route"] || env["action_dispatch.route"]
+        return false unless status && (status.to_i.between?(200, 299) || status.to_i == 304)
+        return false unless env["REQUEST_METHOD"] == "GET" || env["REQUEST_METHOD"] == "HEAD"
+
+        path = Rack::Utils.unescape_path(env["PATH_INFO"].to_s.chomp("/"))
+        return false unless Rack::Utils.valid_path?(path)
+
+        file = File.join(Rails.public_path.to_s, Rack::Utils.clean_path_info(path))
+        [ file, "#{file}.html", File.join(file, "index.html"), "#{file}.br", "#{file}.gz" ]
+          .any? { |candidate| File.file?(candidate) }
+      rescue StandardError
+        false
+      end
+
       def parent_fields(env, exe, status, headers)
         req = ActionDispatch::Request.new(env)
         route = env["railwatch.route"] || {}

data/lib/railwatch/subscribers/exceptions.rb

@@ -248,15 +248,33 @@ module Railwatch
         error.class.ancestors.any? { |ancestor| (name = ancestor.name) && ignored.include?(name) }
       end
 
+      # An IPv6 address, full ("2607:fb90:...:74c7") or compressed around
+      # "::" ("2600:3c15::2000:22ff:febb:8bb9", "2a03:2880:f802:c::"). It
+      # has to carry a digit and stand alone, and it is lower case, as
+      # RFC 5952 and IPAddr write it: so a constant path like Foo::Bar or
+      # Abc1::Def stays, and a clock time like 12:30:45 has neither eight
+      # groups nor a "::".
+      IPV6 = /
+        (?<![\w:])
+        (?=[0-9a-f:]*\d)
+        (?:
+          [0-9a-f]{1,4}(?::[0-9a-f]{1,4}){7}
+          | (?:[0-9a-f]{1,4}(?::[0-9a-f]{1,4}){0,6})?::(?:[0-9a-f]{1,4}(?::[0-9a-f]{1,4}){0,6})?
+        )
+        (?![\w:])
+      /x
+
       # Variable data that would otherwise split one issue into thousands of
       # them. Applied in this order: a URL before the numbers inside it, a
-      # quoted string before the id it quotes, hex before plain digits.
+      # quoted string before the id it quotes, an IPv6 address and hex before
+      # plain digits.
       MESSAGE_NOISE = [
         %r{\bhttps?://\S+},                                  # URLs
         /\b[^\s@]+@[^\s@]+\.[^\s@]+\b/,                      # email addresses
         /\h{8}-\h{4}-\h{4}-\h{4}-\h{12}/,                    # UUIDs
         /\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}\S*/,         # ISO timestamps
         /\b\d{1,3}(?:\.\d{1,3}){3}\b/,                       # IPv4 addresses
+        IPV6,                                                # IPv6, before hex and digits
         /(?<!\w)'[^']*'|"[^"]*"/,                             # quoted strings ("won't" is not one)
         /\b(?:0x)?\h{6,}\b/,                                 # hex: digests, object addresses
         /\b\d+\b/                                            # plain integers

data/lib/railwatch/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Railwatch
-  VERSION = "1.5.0"
+  VERSION = "1.6.0"
 end

data/lib/railwatch.rb

@@ -199,6 +199,18 @@ module Railwatch
       Current.execution = exe&.parent_execution
     end
 
+    # Ends the execution and ships nothing of it, for one that turned out
+    # not to be worth a record at all (the request middleware's static
+    # files). A profile it started is stopped and thrown away.
+    def discard_execution
+      exe = Current.execution
+      return unless exe
+
+      Profiler.stop if exe.profiler_handle
+      Current.execution = exe.parent_execution
+      nil
+    end
+
     # --- record writing --------------------------------------------------------
 
     # Records that make sense without a parent execution (console, boot).

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: railwatch
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Cole Robertson