railwatch 0.3.6 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7670085bcbae37c58def37c8e23ffee964be9277a57462869346017016c33a3c
-  data.tar.gz: fb68d72c0863778eb607cfd2bded53714651caaecffefbff20994e25422a1411
+  metadata.gz: e3cbe26df2ef93b1488b1cfb67d2cb15bb9c2930f63607651af4e5a9d4f526cb
+  data.tar.gz: b62edbbb492f16ef449e4bc7ccc57ad90206f67c0e538c24232b30d931290339
 SHA512:
-  metadata.gz: 429bb5789a56059dce9848403622511df0f5094c2efe4a6ed8c51e5086fb11eaf56b8c762ee9ae68d1ae393a5fae7af65d628df019f01b00466644e207aa6b1d
-  data.tar.gz: 0c38280c362f3529ca2af1e93a6982d77ed15a872351072727dd1152396ea2c3f1a2e634f1132a6cac83bf0ee152f818fda15db76e2251a3f0f1a7a24db5bfb1
+  metadata.gz: dc2578bf58e017c5f311d9642c9b51f52c7c203a84328d8bbe7845568c0836afe5bc7cbec5327aa286cd9e4bb378e930111cedce72b27337f2608e36a6305484
+  data.tar.gz: 2e4f1467282564b4ef5d6d3f1446acb80f6cbfdf116588df899bb5a0cb3172330b817282d7d797d29d0cced2b7ab6aa1688d6fa266324d1634fcdafbb3cfe0df

data/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 0.4.0 (2026-09-21)
+
+The gem is the one author of what goes over the wire and what runs in the
+browser. Anything that receives from it, Railwatch Cloud first, reads these
+from the gem instead of keeping a copy.
+
+- **One browser client.** The gem carried two: the install template wrote
+  the `railwatch_session` cookie that `Railwatch::Sessions` reads, while the
+  dashboard's own copy still wrote `lantern_session`, so every embedded
+  dashboard shipped a beacon whose sessions never stitched to their server
+  requests. There is one file now, `app/frontend/lib/railwatch.ts`, shipped
+  in the gem (`Railwatch.browser_client_path`): the dashboard bundle is built
+  from it, `railwatch:install` copies it, and a host with its own frontend
+  build imports it. A spec holds the cookie name to the regex.
+- **Shipped wire fixtures.** `lib/railwatch/wire_fixtures.json` holds one
+  record per type in `Railwatch::Record::VERSIONS`, produced by the gem's own
+  subscribers and middleware, stabilized, and checked in.
+  `Railwatch.wire_fixtures` loads it. A receiver tests its mapper against
+  these rather than hand-writing what it remembers the gem sending. The spec
+  that generates them fails when the file is stale; `rake
+  railwatch:wire_fixtures` regenerates it, and that diff is the review
+  surface for a wire change.
+- **Record versions are enforced.** Every record has carried a `v` since the
+  first release and no receiver read it. `Railwatch::Ingest::Mapper` now
+  refuses a record whose version is not the one this gem emits for its type,
+  by name (`log v2 is not v1`), on both the trusted embedded path and the
+  untrusted one. A shape change without a version bump is caught by the
+  fixture spec; a version bump the receiver has not shipped is refused
+  instead of misread.
+- `Railwatch::Transport::Http::HEADERS` names the delivery headers in one
+  place for the receiver to read.
+
+## 0.3.7 (2026-09-20)
+
+- Stop a rake task or `rails runner` waiting on the network as it finishes.
+  The command patches called `Railwatch.flush` when the execution closed --
+  on the application's own thread, with no time limit. The engine's `at_exit`
+  already calls `Reporter#shutdown`, which wakes the reporter thread and joins
+  it for `shutdown_timeout`, so the same records were already being delivered,
+  already bounded, and a failed task's exception already went with them. The
+  flush was a second, unbounded way to do it.
+
+  Against a receiver that accepts connections and never answers, that second
+  way cost a full timeout ladder per process -- measured at ~6s, and ~12s when
+  it queued behind a delivery the reporter thread was already stuck in. An app
+  whose container entrypoint boots Rails eleven times before starting Puma
+  spent that on every boot and lost the deploy to its proxy's timeout. With
+  the call removed the task returns immediately and the process still leaves
+  within `shutdown_timeout`, carrying the same records.
+
+  Only short-lived processes were affected: web and worker processes flush on
+  the reporter's own thread and never blocked. `Railwatch.flush` is unchanged
+  and still public, for a caller who wants to wait on purpose.
+
+- Add a process-level regression that runs a failing rake task against a
+  socket that accepts and never answers, and asserts the task returns without
+  waiting on it and the process exits inside the shutdown bound. In-process
+  examples cannot see this: the cost lives in a socket read and the bound in
+  an `at_exit` join.
+
 ## 0.3.6 (2026-09-20)
 
 - Harden embedded live-stream authorization and telemetry delivery. Bound

data/{lib/generators/railwatch/install/templates → app/frontend/lib}/railwatch.ts

@@ -77,7 +77,11 @@ const DEFAULT_IGNORE_ERRORS = [
   "ResizeObserver loop limit exceeded",
   "ResizeObserver loop completed with undelivered notifications",
 ]
-const DEFAULT_DENY_URLS = [/extensions\//i, /^chrome:\/\//i, /^moz-extension:\/\//i]
+const DEFAULT_DENY_URLS = [
+  /extensions\//i,
+  /^chrome:\/\//i,
+  /^moz-extension:\/\//i,
+]
 
 const SESSION_ID_KEY = "railwatch.session"
 const SESSION_STARTED_KEY = "railwatch.session.at"
@@ -128,10 +132,18 @@ function endpoint() {
 }
 
 function csrf() {
-  return document.querySelector<HTMLMetaElement>('meta[name="csrf-token"]')?.content ?? ""
+  return (
+    document.querySelector<HTMLMetaElement>('meta[name="csrf-token"]')
+      ?.content ?? ""
+  )
 }
 
-function post(payload: { visits: Visit[]; errors: JsError[]; session?: Session; tenant?: string }) {
+function post(payload: {
+  visits: Visit[]
+  errors: JsError[]
+  session?: Session
+  tenant?: string
+}) {
   const body = JSON.stringify(payload)
   const blob = new Blob([body], { type: "application/json" })
   if (navigator.sendBeacon?.(endpoint(), blob)) return
@@ -145,7 +157,12 @@ function post(payload: { visits: Visit[]; errors: JsError[]; session?: Session;
 
 function flush(ended = false) {
   if (queue.length === 0 && errors.length === 0 && !ended) return
-  post({ visits: queue.splice(0, queue.length), errors: errors.splice(0, errors.length), session: beat(ended), tenant: tenant() })
+  post({
+    visits: queue.splice(0, queue.length),
+    errors: errors.splice(0, errors.length),
+    session: beat(ended),
+    tenant: tenant(),
+  })
 }
 
 // The app's tenant resolver runs on the flush path, where a throw would cost
@@ -175,15 +192,23 @@ function startSession() {
   try {
     const existing = sessionStorage.getItem(SESSION_ID_KEY)
     const id = existing ?? randomId()
-    const startedAt = Number(sessionStorage.getItem(SESSION_STARTED_KEY)) || Date.now()
+    const startedAt =
+      Number(sessionStorage.getItem(SESSION_STARTED_KEY)) || Date.now()
     if (!existing) {
       sessionStorage.setItem(SESSION_ID_KEY, id)
       sessionStorage.setItem(SESSION_STARTED_KEY, String(startedAt))
     }
+    // Railwatch::Sessions::COOKIE reads this name to stitch server requests to the browser session.
     document.cookie = `railwatch_session=${id}; path=/; SameSite=Lax`
     session = { id, started_at: startedAt }
     // No duration on the first beat: that is what opens the session.
-    if (!existing) post({ visits: [], errors: [], session: { ...session }, tenant: tenant() })
+    if (!existing)
+      post({
+        visits: [],
+        errors: [],
+        session: { ...session },
+        tenant: tenant(),
+      })
   } catch {
     // sessionStorage is unavailable (private mode, storage disabled).
     // Everything else still reports; this tab just has no session.
@@ -213,7 +238,8 @@ function crumb(kind: Crumb["kind"], text: string) {
 // oldest entries until it fits the byte budget.
 function trail(): Crumb[] {
   const taken = crumbs.slice()
-  while (taken.length > 0 && JSON.stringify(taken).length > MAX_CRUMB_BYTES) taken.shift()
+  while (taken.length > 0 && JSON.stringify(taken).length > MAX_CRUMB_BYTES)
+    taken.shift()
   return taken
 }
 
@@ -223,16 +249,26 @@ function trail(): Crumb[] {
 function describeTarget(target: EventTarget | null): string {
   if (!(target instanceof Element)) return ""
   const id = target.id ? `#${target.id}` : ""
-  const className = typeof target.className === "string" ? target.className.trim() : ""
+  const className =
+    typeof target.className === "string" ? target.className.trim() : ""
   const classes = className ? `.${className.split(/\s+/).join(".")}` : ""
-  const text = target instanceof HTMLInputElement ? "" : (target.textContent ?? "").trim().replace(/\s+/g, " ").slice(0, 80)
+  const text =
+    target instanceof HTMLInputElement
+      ? ""
+      : (target.textContent ?? "").trim().replace(/\s+/g, " ").slice(0, 80)
   return `${target.tagName.toLowerCase()}${id}${classes}${text ? ` "${text}"` : ""}`
 }
 
 function startBreadcrumbs() {
-  document.addEventListener("click", (event) => crumb("click", describeTarget(event.target)), true)
+  document.addEventListener(
+    "click",
+    (event) => crumb("click", describeTarget(event.target)),
+    true,
+  )
   for (const level of ["error", "warn"] as const) {
-    const original = console[level].bind(console) as (...args: unknown[]) => void
+    const original = console[level].bind(console) as (
+      ...args: unknown[]
+    ) => void
     console[level] = (...args: unknown[]) => {
       crumb("console", `${level}: ${args.map(stringify).join(" ")}`)
       original(...args)
@@ -267,14 +303,26 @@ function topFrameUrl(stack: string): string | undefined {
 // the app's own code at all -- an extension, an injected widget, a tag
 // manager. None of those are anything this app can fix.
 function ignored(message: string, stack?: string): boolean {
-  if (ignoreErrors.some((pattern) => (typeof pattern === "string" ? message.includes(pattern) : pattern.test(message)))) return true
+  if (
+    ignoreErrors.some((pattern) =>
+      typeof pattern === "string"
+        ? message.includes(pattern)
+        : pattern.test(message),
+    )
+  )
+    return true
   const url = stack ? topFrameUrl(stack) : undefined
   if (!url) return false
   if (denyUrls.some((pattern) => pattern.test(url))) return true
   return !url.startsWith("/") && !url.startsWith(`${location.origin}/`)
 }
 
-function capture(name: string, message: string, stack?: string, context?: Record<string, unknown>) {
+function capture(
+  name: string,
+  message: string,
+  stack?: string,
+  context?: Record<string, unknown>,
+) {
   if (errors.length >= MAX_ERRORS) return
   if (ignored(message, stack)) return
   const breadcrumbs = trail()
@@ -292,15 +340,28 @@ function capture(name: string, message: string, stack?: string, context?: Record
   // Deduped within the flush, not across the page's life: a render loop
   // throws the same error every retry. (Inertia's re-rejection of a failed
   // request is dropped by identity in the rejection handler instead.)
-  if (errors.some((e) => e.name === error.name && e.message === error.message && e.stack === error.stack)) return
+  if (
+    errors.some(
+      (e) =>
+        e.name === error.name &&
+        e.message === error.message &&
+        e.stack === error.stack,
+    )
+  )
+    return
   errors.push(error)
 }
 
 // Anything at all can be thrown or rejected in JavaScript, not just an
 // Error. A non-Error value is reported under `fallback` with whatever it
 // stringifies to as the message.
-function captureValue(value: unknown, fallback: string, context?: Record<string, unknown>) {
-  if (value instanceof Error) capture(value.name, value.message, value.stack, context)
+function captureValue(
+  value: unknown,
+  fallback: string,
+  context?: Record<string, unknown>,
+) {
+  if (value instanceof Error)
+    capture(value.name, value.message, value.stack, context)
   else capture(fallback, stringify(value), undefined, context)
 }
 
@@ -336,7 +397,11 @@ export function railwatchRootOptions(): {
   onUncaughtError: (error: unknown, info: ReactErrorInfo) => void
 } {
   const report = (error: unknown, info: ReactErrorInfo) =>
-    captureValue(error, "Error", info.componentStack ? { componentStack: info.componentStack } : undefined)
+    captureValue(
+      error,
+      "Error",
+      info.componentStack ? { componentStack: info.componentStack } : undefined,
+    )
   return { onCaughtError: report, onUncaughtError: report }
 }
 
@@ -346,7 +411,12 @@ export function railwatchRootOptions(): {
 function stringify(value: unknown) {
   try {
     if (value instanceof Error) return `${value.name}: ${value.message}`
-    if (Array.isArray(value) || (typeof value === "object" && value !== null && value.toString === Object.prototype.toString)) {
+    if (
+      Array.isArray(value) ||
+      (typeof value === "object" &&
+        value !== null &&
+        value.toString === Object.prototype.toString)
+    ) {
       return JSON.stringify(value).slice(0, MAX_CRUMB_TEXT)
     }
     return String(value)
@@ -376,13 +446,20 @@ function startErrorCapture() {
   })
   window.addEventListener("unhandledrejection", (event) => {
     const reason = event.reason as unknown
-    if (typeof reason === "object" && reason !== null && requestFailures.has(reason)) return
+    if (
+      typeof reason === "object" &&
+      reason !== null &&
+      requestFailures.has(reason)
+    )
+      return
     captureValue(reason, "UnhandledRejection")
   })
   onInertia("exception", (detail) => captureRequestFailure(detail.exception))
   onInertia("networkError", (detail) => captureRequestFailure(detail.error))
   onInertia("invalid", (detail) => captureInvalidResponse(detail.response))
-  onInertia("httpException", (detail) => captureInvalidResponse(detail.response))
+  onInertia("httpException", (detail) =>
+    captureInvalidResponse(detail.response),
+  )
 }
 
 // A visit the user is waiting on: one that shows the progress bar, or the
@@ -402,12 +479,16 @@ function waiting(visit: object): boolean {
 // the next waiting `before`, a waiting `start`, or a reported failure,
 // which can only over-report.
 function idOf(record: object, key: string): string | undefined {
-  const value = key in record ? (record as Record<string, unknown>)[key] : undefined
+  const value =
+    key in record ? (record as Record<string, unknown>)[key] : undefined
   return typeof value === "string" ? value : undefined
 }
 
 function landed(detail: object) {
-  if (foregroundRequest?.id !== undefined && idOf(detail, "visitId") === foregroundRequest.id) {
+  if (
+    foregroundRequest?.id !== undefined &&
+    idOf(detail, "visitId") === foregroundRequest.id
+  ) {
     foregroundRequest = null
   }
 }
@@ -424,10 +505,17 @@ function captureRequestFailure(error: unknown) {
   captureValue(error, "InertiaException")
 }
 
-function onInertia(name: string, handler: (detail: Record<string, unknown>) => void) {
+function onInertia(
+  name: string,
+  handler: (detail: Record<string, unknown>) => void,
+) {
   document.addEventListener(`inertia:${name}`, (event) => {
     const detail = (event as CustomEvent<unknown>).detail
-    handler(typeof detail === "object" && detail !== null ? (detail as Record<string, unknown>) : {})
+    handler(
+      typeof detail === "object" && detail !== null
+        ? (detail as Record<string, unknown>)
+        : {},
+    )
   })
 }
 
@@ -439,19 +527,31 @@ function onInertia(name: string, handler: (detail: Record<string, unknown>) => v
 // predicate for the two cases is the x-inertia response header, so that is
 // the gate here; Inertia 2's `invalid` only ever fired for the first kind.
 function captureInvalidResponse(response: unknown) {
-  const res = (response ?? {}) as { status?: unknown; headers?: Record<string, unknown> }
+  const res = (response ?? {}) as {
+    status?: unknown
+    headers?: Record<string, unknown>
+  }
   if (inertiaResponse(res.headers)) return
   const status = typeof res.status === "number" ? res.status : "unknown status"
   const contentType = res.headers?.["content-type"]
-  capture("InertiaInvalidResponse", `Inertia invalid response (${status})`, undefined, {
-    status,
-    ...(typeof contentType === "string" ? { content_type: contentType } : {}),
-  })
+  capture(
+    "InertiaInvalidResponse",
+    `Inertia invalid response (${status})`,
+    undefined,
+    {
+      status,
+      ...(typeof contentType === "string" ? { content_type: contentType } : {}),
+    },
+  )
 }
 
-function inertiaResponse(headers: Record<string, unknown> | undefined): boolean {
+function inertiaResponse(
+  headers: Record<string, unknown> | undefined,
+): boolean {
   if (!headers || typeof headers !== "object") return false
-  return Object.keys(headers).some((key) => key.toLowerCase() === "x-inertia" && headers[key])
+  return Object.keys(headers).some(
+    (key) => key.toLowerCase() === "x-inertia" && headers[key],
+  )
 }
 
 // --- Core Web Vitals ---------------------------------------------------
@@ -472,10 +572,16 @@ interface ObserveOptions {
   durationThreshold?: number
 }
 
-function observe(type: string, callback: (entries: VitalEntry[]) => void, options: ObserveOptions = {}) {
+function observe(
+  type: string,
+  callback: (entries: VitalEntry[]) => void,
+  options: ObserveOptions = {},
+) {
   if (typeof PerformanceObserver === "undefined") return
   try {
-    const observer = new PerformanceObserver((list) => callback(list.getEntries()))
+    const observer = new PerformanceObserver((list) =>
+      callback(list.getEntries()),
+    )
     observer.observe({ type, buffered: true, ...options })
   } catch {
     // This browser does not support this entry type. Skip that metric only.
@@ -487,9 +593,12 @@ function observe(type: string, callback: (entries: VitalEntry[]) => void, option
 // this file is imported into) does not define, and a ReferenceError here
 // would take the whole client down with it.
 function navigationEntry(): PerformanceNavigationTiming | undefined {
-  const entries: PerformanceEntry[] = performance.getEntriesByType?.("navigation") ?? []
+  const entries: PerformanceEntry[] =
+    performance.getEntriesByType?.("navigation") ?? []
   const nav = entries[0]
-  return nav?.entryType === "navigation" ? (nav as PerformanceNavigationTiming) : undefined
+  return nav?.entryType === "navigation"
+    ? (nav as PerformanceNavigationTiming)
+    : undefined
 }
 
 function startVitals() {
@@ -511,7 +620,11 @@ function startVitals() {
     for (const entry of entries) {
       if (entry.hadRecentInput) continue
       const value = entry.value ?? 0
-      if (sessionValue && entry.startTime - sessionLast < 1000 && entry.startTime - sessionFirst < 5000) {
+      if (
+        sessionValue &&
+        entry.startTime - sessionLast < 1000 &&
+        entry.startTime - sessionFirst < 5000
+      ) {
         sessionValue += value
         sessionLast = entry.startTime
       } else {
@@ -541,7 +654,9 @@ function startVitals() {
 // serialized page object. Inertia's own events take over from here.
 function pageComponent(): string | undefined {
   try {
-    const page = JSON.parse(document.getElementById("app")?.dataset.page ?? "{}") as { component?: string }
+    const page = JSON.parse(
+      document.getElementById("app")?.dataset.page ?? "{}",
+    ) as { component?: string }
     return page.component
   } catch {
     // Not an Inertia-rendered page, or the payload moved. Report it anyway.
@@ -557,7 +672,10 @@ function initialVisit(): Visit | null {
 
   const duration = (nav.loadEventEnd || nav.responseEnd) - nav.startTime
   return {
-    started_at: Math.round((performance.timeOrigin ?? Date.now() - performance.now()) + nav.startTime),
+    started_at: Math.round(
+      (performance.timeOrigin ?? Date.now() - performance.now()) +
+        nav.startTime,
+    ),
     url: location.pathname + location.search,
     method: "GET",
     component,
@@ -587,8 +705,8 @@ function finalize() {
 }
 
 export function startRailwatch(options: RailwatchOptions = {}) {
-  ignoreErrors = [ ...DEFAULT_IGNORE_ERRORS, ...(options.ignoreErrors ?? []) ]
-  denyUrls = [ ...DEFAULT_DENY_URLS, ...(options.denyUrls ?? []) ]
+  ignoreErrors = [...DEFAULT_IGNORE_ERRORS, ...(options.ignoreErrors ?? [])]
+  denyUrls = [...DEFAULT_DENY_URLS, ...(options.denyUrls ?? [])]
   tenantOf = options.tenant
   startVitals()
   startSession()
@@ -609,7 +727,8 @@ export function startRailwatch(options: RailwatchOptions = {}) {
     if (!waiting(v) || event.defaultPrevented) return
     const request = (foregroundRequest = { id: idOf(v, "id") })
     queueMicrotask(() => {
-      if (event.defaultPrevented && foregroundRequest === request) foregroundRequest = null
+      if (event.defaultPrevented && foregroundRequest === request)
+        foregroundRequest = null
     })
   })
   router.on("start", (event) => {
@@ -642,7 +761,8 @@ export function startRailwatch(options: RailwatchOptions = {}) {
   router.on("finish", (event) => {
     // Fires once whether the visit completed, failed, or was cancelled.
     // Clamped so a missed start can only over-report, never silence.
-    if (waiting(event.detail.visit)) foregroundVisits = Math.max(0, foregroundVisits - 1)
+    if (waiting(event.detail.visit))
+      foregroundVisits = Math.max(0, foregroundVisits - 1)
     if (!current) return
     current.duration_ms = Date.now() - current.started_at
     current.status ??= "cancelled"

data/app/models/railwatch/ingest/batch.rb

@@ -182,6 +182,7 @@ module Railwatch
             # batch does not need.
             raise TypeError, "record must be an object" unless rec.is_a?(Hash)
             raise TypeError, "t must be a string" unless rec["t"].is_a?(String)
+            Ingest::Mapper.validate_version!(rec)
           else
             Ingest::Mapper.validate_record!(rec)
           end

data/app/models/railwatch/ingest/mapper.rb

@@ -111,6 +111,7 @@ module Railwatch
       def validate_record!(rec, identifiers: true)
         raise TypeError, "record must be an object" unless rec.is_a?(Hash)
         raise TypeError, "t must be a string" unless rec["t"].is_a?(String)
+        validate_version!(rec)
 
         if identifiers
           validate_identifier!(rec, "_group", GROUP_HASH, "32 hexadecimal characters")
@@ -129,6 +130,17 @@ module Railwatch
         validate_locals!(rec["locals"])
       end
 
+      # A record shape is named by its type and version (Railwatch::Record::VERSIONS).
+      # This mapper only knows the versions the gem it ships with emits; a
+      # record from a newer or older gem is refused by name rather than read
+      # through columns that may no longer mean the same thing.
+      def validate_version!(rec)
+        expected = Record::VERSIONS[rec["t"].to_sym]
+        return if expected.nil? # unknown type: row_for answers nil and the batch rejects it as such
+
+        raise TypeError, "#{rec["t"]} v#{rec["v"].inspect} is not v#{expected}" unless rec["v"].is_a?(Integer) && rec["v"] == expected
+      end
+
       def validate_identifier!(rec, field, pattern, description)
         value = rec[field]
         return if value.nil?

data/docs/configuration.md

@@ -431,9 +431,14 @@ affects one probabilistic decision. Set `backpressure` false to keep the
 factor at 1. The current value is sent as
 `X-Railwatch-Backpressure-Factor` whenever it is greater than 1.
 
-`Railwatch.flush` forces an immediate flush. The `command` patches also
-call it after a rake task/runner invocation finishes, so short-lived
-processes don't lose their last batch to the flush interval. An unhandled
+`Railwatch.flush` forces an immediate flush, on the calling thread and
+without a time limit, so it is yours to call when you know you want to
+wait. Nothing in the gem calls it for you: a short-lived process keeps its
+last batch because the engine's `at_exit` runs `Reporter#shutdown`, which
+wakes the reporter thread and joins it for `shutdown_timeout`. That is a
+bounded wait, which is what a rake task, a runner or a cron job needs --
+a receiver that accepts connections and never answers then costs
+`shutdown_timeout`, not a timeout ladder per process. An unhandled
 exception goes through `Railwatch.record_now` → `Reporter#write_now`,
 which enqueues the record and asks for an urgent flush. It never performs
 network I/O or a timeout cycle on the application thread. Urgent means

data/lib/generators/railwatch/install/install_generator.rb

@@ -119,9 +119,13 @@ module Railwatch
         chmod ".kamal/hooks/post-deploy", 0o755
       end
 
+      # The one browser client, the same file the gem's own dashboard bundle
+      # is built from (Railwatch.browser_client_path). Copied rather than
+      # templated: there is nothing to interpolate, and a copy means the host
+      # sees exactly what the gem tests.
       def create_browser_client
         return unless File.directory?("app/frontend")
-        template "railwatch.ts", "app/frontend/lib/railwatch.ts"
+        copy_file Railwatch.browser_client_path.to_s, "app/frontend/lib/railwatch.ts"
       end
 
       # Adds the import and the call to the Inertia entrypoint, so page-visit

data/lib/railwatch/patches/rake_task.rb

@@ -72,7 +72,16 @@ module Railwatch
             name: name,
             command: "rake #{name}#{command_suffix}",
             exit_code: exit_code.to_i.clamp(0, 255))
-          Railwatch.flush
+          # Deliberately no flush. The engine's at_exit calls Reporter#shutdown,
+          # which wakes the reporter thread and joins it for shutdown_timeout --
+          # already a bounded last delivery, and already the one that ships a
+          # failed task's exception. Flushing here as well delivered the same
+          # records a second way, on the application's own thread, with no
+          # bound: against a receiver that accepts connections and never
+          # answers it cost a full timeout ladder per process, measured at ~6s,
+          # and ~12s when it queued behind a delivery the reporter thread was
+          # already stuck in. An app whose entrypoint boots Rails eleven times
+          # spent that eleven times over and lost the deploy.
         end
       end
 

data/lib/railwatch/patches/runner_command.rb

@@ -91,7 +91,9 @@ module Railwatch
           }
           fields[:interactive] = true if interactive
           Railwatch.finish_execution(:command, **fields)
-          Railwatch.flush
+          # No flush here either; see the note in patches/rake_task.rb. The
+          # at_exit shutdown is the bounded delivery, and it runs for a runner
+          # exactly as it does for a task.
         end
       end
 

data/lib/railwatch/transport/http.rb

@@ -13,6 +13,16 @@ module Railwatch
     # Reporter owns retention and backoff between calls. A 401 marks the
     # transport unauthorized so no further requests are made.
     class Http
+      # The request headers a delivery carries besides the body. The receiver
+      # reads them by these names; Railwatch Cloud does so through this table.
+      HEADERS = {
+        dropped: "X-Railwatch-Dropped",
+        dropped_bytes: "X-Railwatch-Dropped-Bytes",
+        backpressure_factor: "X-Railwatch-Backpressure-Factor",
+        version: "X-Railwatch-Version",
+        batch_id: "X-Railwatch-Batch-Id"
+      }.freeze
+
       RETRYABLE_STATUSES = [ 402, 408, 429 ].freeze
       UNAUTHORIZED_STATUS = 401
 
@@ -143,17 +153,17 @@ module Railwatch
         headers.each { |name, value| req[name] = value.to_s }
         req["Content-Type"] = "application/x-ndjson"
         req["Content-Encoding"] = "gzip"
-        req["X-Railwatch-Dropped"] = dropped.to_s if dropped.positive?
-        req["X-Railwatch-Dropped-Bytes"] = dropped_bytes.to_s if dropped_bytes.positive?
+        req[HEADERS[:dropped]] = dropped.to_s if dropped.positive?
+        req[HEADERS[:dropped_bytes]] = dropped_bytes.to_s if dropped_bytes.positive?
         if backpressure_factor > 1.0
-          req["X-Railwatch-Backpressure-Factor"] = backpressure_factor.to_s
+          req[HEADERS[:backpressure_factor]] = backpressure_factor.to_s
         end
         # The version this payload was built by, which for a stored delivery is
         # not the version running now. The receiver digests this header, so
         # sending today's value would turn an upgrade into a conflict and
         # destroy a delivery it had already accepted.
-        req["X-Railwatch-Version"] = gem_version
-        req["X-Railwatch-Batch-Id"] = batch_id
+        req[HEADERS[:version]] = gem_version
+        req[HEADERS[:batch_id]] = batch_id
         req.body = body
         request(req)
       end

data/lib/railwatch/version.rb

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