railwatch 1.4.0 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 954add09993af5d0756ed9ff1875061f25eed72867139116fd020a90b961627c
-  data.tar.gz: 6fbb618b6eb38d867f9ea7648dfce28d7c46003e1ed9499303a3889de06373af
+  metadata.gz: fd59ae7a65fbd673b2069d096802144c04277a08379fa42285d32677ad5502c6
+  data.tar.gz: 49ff48d1ec8340609c23c12a117ae1e381ac938f7fbdfb6aa914b7e33505a25c
 SHA512:
-  metadata.gz: 88f0a50d4769269d565513d59b03567413424f6566da76d1056d08a1e734d7ce244bc609a06c8a25cd7651873ae1519af968a5f6708b225cb984cb764ab77387
-  data.tar.gz: b882ad5f4cb5a5a3ed16975d1cab018fdd04a0e75be8677baa29882dcc61c56b561096568241e023843d687dc950324a16dedc20200dd4035f51f949535b20c5
+  metadata.gz: 9c45c3639f2787b16b9104afed286ff712bfb63028e13fd83eda44323544ddb9a156c60566287d5465d6daaeffb46b4a8379addb8a51ebf90ab178f9c17a41d4
+  data.tar.gz: 31fe3a1492400bf823ef7dbd04ee22a45edda63349168032b93a3f8e429525cf9cb205b15b96eb6238819a6386916457a75ed3f4de52164227c39e39c8a1a576

data/CHANGELOG.md

@@ -6,6 +6,33 @@
      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.5.0 (2026-10-28)
+
+- The browser session is one per browser, shared by every tab, as in GA4
+  and Amplitude: kept in `localStorage`, it ends after 30 minutes with no
+  activity in any tab or 24 hours after it started. Each tab also has its
+  own id. Every visit record carries `session_id` and `tab_id`, and every
+  request record carries the `session_id` from the `X-Railwatch-Session`
+  header or `railwatch_session` cookie and the `tab_id` from
+  `X-Railwatch-Tab`, which the client now sends on same-origin Inertia
+  visits. A browser error's `context.browser` carries the `session` and
+  `tab` it was thrown in, stamped when it fired, and both are dropped
+  rather than cut when they are not shaped like an id. A browser's first
+  page load, which arrives before the client has set its cookie, is handed
+  one by the request middleware (successful HTML `GET`s only, never a
+  publicly cacheable one, and only when the browser client is installed:
+  `browser_client`), so that page is in the session's journey and no
+  longer opens a second `user:<id>` session in release health. A closing
+  tab no longer marks the session `ended`: the browser's other tabs may
+  still be in it. Apps that copied the client
+  (`app/frontend/lib/railwatch.ts`) need the same change in their copy:
+  `bin/rails generate railwatch:install --force --no-doctor` updates it.
+- `railwatch:install`, `railwatch:doctor` and the `browser_client`
+  detection find the app's frontend sources in ViteRuby's `sourceCodeDir`,
+  else in `app/frontend` or `app/javascript`. They only looked in
+  `app/frontend` before, so an `app/javascript` app got no client and no
+  entrypoint wiring.
+
 ## 1.4.0 (2026-10-26)
 
 - In development each recorded request's response carries

data/app/controllers/railwatch/beacon_controller.rb

@@ -55,6 +55,7 @@ module Railwatch
           inp: metric_ms(v["inp"]),
           ttfb: metric_ms(v["ttfb"]),
           **ttfb_phases(v),
+          **browser_fields(v),
           user: user_id,
           tenant: tenant,
           user_agent: safe_string(request.user_agent, 256))
@@ -193,7 +194,7 @@ module Railwatch
         next unless error
         name = safe_string(error["name"], 255)
         next if name.empty?
-        record_error(error, name, origin, session_id, user_id, tenant)
+        record_error(error, name, origin, Sessions.browser_id(error["session_id"]) || session_id, user_id, tenant)
       end
     end
 
@@ -206,12 +207,19 @@ module Railwatch
       Context.current_tenant || (hint.is_a?(String) ? safe_string(hint, 255).presence : nil)
     end
 
-    # The tab's session id, so a browser error can be lined up with the
-    # session it crashed. Shaped like every other read off this payload:
-    # anything but a hash carrying an id yields no id at all.
+    # The flush's session id, for an error that does not name its own (a
+    # client copied before errors carried one). Anything but a hash carrying
+    # an id shaped like one the client mints yields no id at all.
     def session_id_from(session)
       session = object(session)
-      session ? safe_string(session["id"], 64) : ""
+      Sessions.browser_id(session["id"]) if session
+    end
+
+    # The session and tab each visit says it happened in, which can differ
+    # within one beacon: visits queued before the session timed out ship
+    # with the next session's beat. Omitted unless shaped like an id.
+    def browser_fields(visit)
+      { session_id: Sessions.browser_id(visit["session_id"]), tab_id: Sessions.browser_id(visit["tab_id"]) }.compact
     end
 
     def record_error(error, name, origin, session_id, user_id, tenant)
@@ -235,7 +243,8 @@ module Railwatch
           url: safe_string(error["url"], 2048).presence,
           component: safe_string(error["component"], 255).presence,
           visit: safe_string(error["visit"], 2048).presence,
-          session: session_id.presence,
+          session: session_id,
+          tab: Sessions.browser_id(error["tab_id"]),
           user_agent: safe_string(request.user_agent, 256).presence,
           breadcrumbs: breadcrumbs(error["breadcrumbs"]).presence
         }.compact)),

data/docs/configuration.md

@@ -523,15 +523,21 @@ crash-free session and crash-free user rates are computed from. The
 | `track_sessions` | `RAILWATCH_TRACK_SESSIONS` | `true` | Master switch for both session sources. Off means the request middleware does nothing extra and no flusher thread is started. |
 | `session_flush_interval` | `RAILWATCH_SESSION_FLUSH_INTERVAL` | `60.0` | Seconds between server-session flushes. One background thread per web process, re-armed after `fork` exactly like the health sampler, and flushed once more on shutdown. |
 | `session_timeout` | `RAILWATCH_SESSION_TIMEOUT` | `1800.0` | Seconds a server session may sit idle before it ships with `ended` and is forgotten. |
+| `browser_client` | `RAILWATCH_BROWSER_CLIENT` | whether `lib/railwatch.ts` exists in the app's frontend source directory (ViteRuby's `sourceCodeDir`, else `app/frontend` or `app/javascript`) | Whether the app's pages run the browser client. When they do, a browser's first page load gets its session id from the server (below). Set it when the client lives somewhere else, or `false` to never set the cookie. |
 
 There are two sources, and they meet on the same id:
 
 - **The browser client** is `app/frontend/lib/railwatch.ts`, installed by
-  `railwatch:install`. It mints one id per tab in `sessionStorage` and
-  mirrors it into a `railwatch_session` cookie. It rides along on the
-  beacon flushes the client already sends for visits, so this costs no
-  extra requests. This is the primary source for a web app, and it is
-  what makes session duration mean "how long the tab was open".
+  `railwatch:install`. It keeps one id per browser in `localStorage`,
+  shared by every tab and replaced after 30 minutes with no activity in
+  any tab or 24 hours after it started, and mirrors it into a
+  `railwatch_session` cookie. It also sends the id, with the tab's own
+  id, as `X-Railwatch-Session` and `X-Railwatch-Tab` on every Inertia
+  visit to the page's own origin. It rides along on the beacon flushes
+  the client already sends for visits, so this costs no extra requests.
+  This is the primary source for a web app, and it is what makes session
+  duration mean "how long the user was active". The client's 30 minutes
+  is fixed; it matches this setting's default.
 - **The request middleware** aggregates, in memory, every request that
   either resolves a user or carries that cookie or an
   `X-Railwatch-Session` header. It is the only source for an API-only
@@ -541,6 +547,25 @@ There are two sources, and they meet on the same id:
 When a browser session's requests carry the cookie both sources produce
 records under the same id and the platform dedupes them.
 
+A browser's first page load arrives before the client has run, so it
+carries no cookie. With `browser_client` on, the request middleware gives
+it one: a successful `GET` whose response is an HTML document, that is not
+an Inertia visit and carries no `X-Railwatch-Session` or cookie, gets
+`Set-Cookie: railwatch_session=<new id>; path=/; max-age=1800;
+samesite=lax` (plus `secure` over HTTPS, including behind a proxy that
+sets `X-Forwarded-Proto`). That request's record carries the id, and so does its
+server session when it resolved a user (an anonymous one opened no server
+session before and still opens none; its browser opens the session with
+the client's first beat).
+The client adopts it when the browser has no live session of its own, so
+that first page is the first entry of the session's journey and the
+session is not counted twice (once under the id, once as `user:<id>`). It
+is never set on a response whose `Cache-Control` says `public` or
+`s-maxage`, since a shared cache would hand one visitor's cookie to every
+visitor; on such a page the session starts with the client, as before.
+Requests with neither cookie nor header, from an API client or an app
+without the browser client, still key on `user:<id>`.
+
 ## Vendor noise defaults
 
 Framework/vendor activity excluded by default so a fresh install isn't
@@ -719,7 +744,9 @@ credential, so it is throttled per client IP by `beacon_rate_limit`,
 default 120 a minute, `0` to disable. A client past the limit gets a 429
 with `Retry-After` and nothing from that POST is recorded. Client setup:
 call `startRailwatch()` from your Inertia entrypoint. It is generated at
-`app/frontend/lib/railwatch.ts`.
+`lib/railwatch.ts` in the app's frontend source directory, usually
+`app/frontend/lib/railwatch.ts` (see Getting started for how the directory
+is chosen and how to update the copy).
 
 `startRailwatch` takes three optional settings, none of which has a
 server-side equivalent. They are decisions about the browser the code is

data/docs/getting-started.md

@@ -57,9 +57,25 @@ bin/rails generate railwatch:install \
   beacon endpoint the browser client posts to (`POST /railwatch/beacon`).
 - `.kamal/hooks/post-deploy` — only if `config/deploy.yml` already
   exists.
-- `app/frontend/lib/railwatch.ts` plus the `startRailwatch()` call in your
-  Inertia entrypoint — only if `app/frontend/` exists. If it can't find
-  an entrypoint it prints the two lines to add.
+- `lib/railwatch.ts` in the app's frontend source directory, plus the
+  `startRailwatch()` call in its Inertia entrypoint
+  (`entrypoints/inertia.tsx`, `.ts` or `.jsx`). The directory is ViteRuby's
+  `sourceCodeDir` when the app uses vite_ruby, else the first of
+  `app/frontend` and `app/javascript` that exists; with neither, nothing
+  is copied. If it can't find an entrypoint it prints the two lines to add.
+
+The browser client is copied into the app, so upgrading the gem does not
+update it. After an upgrade whose CHANGELOG mentions the client, run
+`bin/rails generate railwatch:install --force --no-doctor`, or copy the
+file by hand:
+
+```sh
+cp "$(bundle exec ruby -e 'require "railwatch"; print Railwatch.browser_client_path')" app/frontend/lib/railwatch.ts  # or app/javascript/lib/...
+```
+
+Without `--force` the generator asks before overwriting a copy that
+differs. Either way, review the diff if you have edited your copy. The
+generator's other steps leave what they already wrote alone.
 - `require "railwatch/rspec"` in `spec/rails_helper.rb`, or
   `require "railwatch/minitest"` in `test/test_helper.rb`.
 

data/docs/records.md

@@ -104,6 +104,8 @@ boundaries. The `action`/`render` boundaries come from
 | `payload` | Filtered request params — only captured when `config.capture_request_payload` is on **and** the request raised an exception (never for successful requests). |
 | `user_agent` | Truncated to 256 chars. |
 | `files` | Array of `{name, size, content_type, error}` for each uploaded file in a multipart request (metadata only, never contents). A non-multipart request body is never parsed to fill this in. |
+| `session_id` | The browser client's session id, from `X-Railwatch-Session` or else the `railwatch_session` cookie, so a full page load carries it too. On a browser's first page load, the id the middleware set in that cookie on this response (see Release health in configuration.md). Never the `"user:<id>"` key the server session falls back to. At most 64 of `[A-Za-z0-9_-]`; absent when missing or not that shape. |
+| `tab_id` | The browser client's tab id, from `X-Railwatch-Tab`, which it sends only on Inertia visits: a full page load has none. Same validation, absent otherwise. |
 | `profiled` | `true` when a `profile` record shipped for this request; absent otherwise. |
 
 ### `job_attempt`
@@ -396,8 +398,10 @@ the normalized message. So browser errors group, split, merge, resolve,
 and regress through the same Issue machinery.
 
 `context` carries a `browser` key with the page `url`, the Inertia
-`component`, the `visit` the error happened in if any, the tab's
-`session` id, the `user_agent`, and up to 20 `breadcrumbs`. Each
+`component`, the `visit` the error happened in if any, the browser
+`session` id and the `tab` id it was thrown in, both stamped by the client
+when the error fired (the flush's session stands in for a client that
+sends none; each at most 64 of `[A-Za-z0-9_-]`, absent otherwise), the `user_agent`, and up to 20 `breadcrumbs`. Each
 breadcrumb is `{at, kind, text}`, with `kind` being `console`, `click`,
 or `navigate`. The breadcrumbs are the trail the client recorded before
 the crash. Anything the app passed as `reportError(error, context)` is
@@ -776,6 +780,8 @@ entirely if `config.beacon_enabled` is off.
 | `user` | Resolved server-side from the beacon request's session/cookies, same resolver as every other record. |
 | `tenant` | Current tenant context. |
 | `user_agent` | Truncated to 256 chars. |
+| `session_id` | The browser session the visit happened in (see `session`), when the client sent one shaped like an id: at most 64 of `[A-Za-z0-9_-]`. Absent otherwise. |
+| `tab_id` | The tab the visit happened in: a 16-hex id the client keeps in `sessionStorage` (`railwatch.tab`), so it survives a reload of the tab but not a new tab. "Duplicate tab" copies `sessionStorage`, so a duplicated tab shares its original's id until one of them is reloaded fresh. Same validation, absent otherwise. |
 
 The **initial page load** is reported as a visit too, even though Inertia
 never routed it. It has `method` `"GET"`, `status` `"success"`, and
@@ -799,13 +805,25 @@ per deploy and reports crash-free rates from them. Two sources produce
 the same record:
 
 - **Browser**, `source: "browser"`. The client,
-  `app/frontend/lib/railwatch.ts`, mints a 16-hex id per tab in
-  `sessionStorage` under the key `railwatch.session`, so it dies with the
-  tab. It mirrors the id into a `railwatch_session` cookie and sends it
-  with every beacon flush. `Railwatch::BeaconController` writes at most
-  one `session` record per flush. The first, with no `duration_ms` yet,
-  opens the session. Later ones beat it along, and the
-  `pagehide`/`visibilitychange` flush closes it with `ended`.
+  `app/frontend/lib/railwatch.ts`, keeps one session per browser, shared
+  by every tab, the way GA4 and Amplitude do: a 16-hex id in
+  `localStorage` (`railwatch.session`, with `railwatch.session.at` when it
+  started and `railwatch.session.seen` for its last activity in any tab).
+  Activity is a page load, an Inertia visit the user waits on, and a tab
+  coming back into view. After 30 minutes with no activity in any tab, or
+  24 hours after it started, the next activity mints a new id. When
+  `localStorage` throws the session lives in `sessionStorage`, and when
+  that throws too, in memory; a new tab still joins the session through
+  the cookie. A browser's first page load gets its id from the server, in
+  that cookie, and the client adopts it when no live session is stored.
+  The client mirrors the id into a `railwatch_session` cookie that lapses
+  after 30 minutes, renewed on every activity, and sends it with every
+  beacon flush. `Railwatch::BeaconController` writes at most one `session` record
+  per flush. The first, with no `duration_ms` yet, opens the session.
+  Later ones beat it along. Closing a tab does not end the session, since
+  other tabs may still be in it; a tab that sees the session time out
+  sends one last beat with `ended`, and a session no tab comes back to
+  ends only by the platform's own timeout.
 - **Server**, `source: "server"`. `lib/railwatch/sessions.rb` aggregates,
   per process, every request that resolves a user or carries that cookie
   or an `X-Railwatch-Session` header. A background thread ships one
@@ -830,7 +848,7 @@ halves of one session rather than counting it twice.
 | `requests` | Requests in this session so far (server only). |
 | `visits` | Inertia visits in this beacon flush (browser only). |
 | `errors` | Requests that 5xx'd or raised (server), or visits with status `"error"` in this flush (browser). |
-| `ended` | Whether this is the session's last record. |
+| `ended` | Whether this is the session's last record. A browser session is only `ended` when a tab saw it time out, never because a tab closed. |
 | `user` | Resolved user id, when there is one. |
 
 ### `process`

data/docs/troubleshooting.md

@@ -26,7 +26,7 @@ the install is broken.
 | `ignored record types` | Never fails; it prints what `c.ignore` is dropping. |
 | `interactive sessions` | Never fails; it prints whether consoles are captured and the runner scratch paths. |
 | `kamal post-deploy hook` | `.kamal/hooks/post-deploy` is missing or doesn't mention Railwatch. Only matters if you deploy with Kamal. |
-| `browser client` | `app/frontend/lib/railwatch.ts` isn't there. Only matters for Inertia visit timing. |
+| `browser client` | `lib/railwatch.ts` isn't in the app's frontend source directory (ViteRuby's `sourceCodeDir`, else `app/frontend` or `app/javascript`). Only matters for Inertia visit timing. |
 | `browser client imported` | The client exists but nothing calls `startRailwatch()` — no `startRailwatch` found in `app/frontend/entrypoints`. Visits won't report. |
 | `profiler backend` | Neither `vernier` nor `stackprof` is installed, so `Railwatch::Profiler.available?` is false and the profiling settings are inert. |
 | `test matchers` | Neither `spec/rails_helper.rb` requires `railwatch/rspec` nor `test/test_helper.rb` requires `railwatch/minitest`. |

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

@@ -23,11 +23,12 @@ module Railwatch
       class_option :doctor, type: :boolean, default: true,
                             desc: "Run railwatch:doctor when the install finishes."
 
-      # Whichever of these exists is where `startRailwatch()` is added.
+      # Whichever of these exists, under the app's frontend source directory
+      # (Railwatch.frontend_dir), is where `startRailwatch()` is added.
       INERTIA_ENTRYPOINTS = %w[
-        app/frontend/entrypoints/inertia.tsx
-        app/frontend/entrypoints/inertia.ts
-        app/frontend/entrypoints/inertia.jsx
+        entrypoints/inertia.tsx
+        entrypoints/inertia.ts
+        entrypoints/inertia.jsx
       ].freeze
 
       IMPORT_LINE = 'import { startRailwatch } from "@/lib/railwatch"'
@@ -68,19 +69,22 @@ module Railwatch
 
       # The one browser client (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.
+      # host sees exactly what the gem tests. Re-running the generator after
+      # a gem upgrade is how an app picks up a new client: Thor asks before
+      # overwriting a copy that differs (--force overwrites, --skip keeps it).
       def create_browser_client
-        return unless File.directory?("app/frontend")
-        copy_file Railwatch.browser_client_path.to_s, "app/frontend/lib/railwatch.ts"
+        return unless frontend_dir
+        copy_file Railwatch.browser_client_path.to_s, "#{frontend_dir}/lib/railwatch.ts"
       end
 
       # Adds the import and the call to the Inertia entrypoint, so page-visit
       # timing and Core Web Vitals report with no further editing.
       def start_browser_client
-        return unless File.directory?("app/frontend")
+        return unless frontend_dir
 
-        path = INERTIA_ENTRYPOINTS.find { |candidate| File.exist?(candidate) }
-        return say(browser_client_instructions(INERTIA_ENTRYPOINTS.first), :yellow) unless path
+        candidates = INERTIA_ENTRYPOINTS.map { |entrypoint| "#{frontend_dir}/#{entrypoint}" }
+        path = candidates.find { |candidate| File.exist?(candidate) }
+        return say(browser_client_instructions(candidates.first), :yellow) unless path
 
         contents = File.read(path)
         return say_status(:identical, path, :blue) if contents.include?(START_CALL)
@@ -279,6 +283,10 @@ module Railwatch
           "The token value is never printed:\n#{lines.join("\n")}"
       end
 
+      def frontend_dir
+        @frontend_dir ||= Railwatch.frontend_dir(destination_root)
+      end
+
       def browser_client_instructions(path)
         "Add these two lines to #{path} to report Inertia visits and Core Web Vitals:\n" \
           "  #{IMPORT_LINE}\n  #{START_CALL}"

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

@@ -29,10 +29,13 @@ interface Visit {
   redirect_count?: number
   connect_ms?: number
   server_ms?: number
+  // The browser session and the tab the visit happened in, for the journey.
+  session_id?: string
+  tab_id?: string
 }
 
-// The tab's session, for release health. sessionStorage scopes it to the
-// tab and it dies with the tab, which is what a browser session is.
+// The browser's session, for release health and the session journey, on the
+// wire. `ended` only when this tab has seen it time out (see `begin`).
 interface Session {
   id: string
   started_at: number
@@ -50,6 +53,10 @@ interface JsError {
   component?: string
   url: string
   visit?: string
+  // The session and tab it was thrown in, taken when it was: another tab
+  // may move the session on before this one flushes.
+  session_id?: string
+  tab_id?: string
   breadcrumbs?: Crumb[]
   context?: Record<string, unknown>
 }
@@ -90,14 +97,26 @@ const DEFAULT_DENY_URLS = [
 ]
 
 const SESSION_ID_KEY = "railwatch.session"
+const SESSION_SEEN_KEY = "railwatch.session.seen"
 const SESSION_STARTED_KEY = "railwatch.session.at"
+const TAB_KEY = "railwatch.tab"
+// The GA4/Amplitude rules: a session is over after 30 minutes with no
+// activity in any tab (config.session_timeout's default, which the server
+// half times out on too), and after 24 hours whatever happens.
+const SESSION_TIMEOUT_MS = 30 * 60 * 1000
+const SESSION_CAP_MS = 24 * 60 * 60 * 1000
+// Railwatch::Sessions reads these, ahead of the cookie.
+const SESSION_HEADER = "X-Railwatch-Session"
+const TAB_HEADER = "X-Railwatch-Tab"
 
 const queue: Visit[] = []
 const errors: JsError[] = []
 const crumbs: Crumb[] = []
 let current: Visit | null = null
 let initial: Visit | null = null
-let session: Session | null = null
+// `seen` is the session's last activity in any tab, as far as this one knows.
+let session: { id: string; started_at: number; seen: number } | null = null
+let tab = ""
 // The Inertia page component the user is on, so an error that fires between
 // visits still says which screen it broke.
 let component: string | undefined
@@ -170,12 +189,13 @@ function post(payload: {
   }).catch(() => undefined)
 }
 
-function flush(ended = false) {
-  if (queue.length === 0 && errors.length === 0 && !ended) return
+function flush(force = false) {
+  if (queue.length === 0 && errors.length === 0 && !force) return
+  touch(false)
   post({
     visits: queue.splice(0, queue.length),
     errors: errors.splice(0, errors.length),
-    session: beat(ended),
+    session: beat(),
     tenant: tenant(),
   })
 }
@@ -199,40 +219,220 @@ function randomId() {
   return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("")
 }
 
-// Mints the tab's session on its first load, or picks up the one an earlier
-// page in this tab minted, and mirrors the id into a cookie so every request
-// the tab makes carries it -- that is what lets the server side of the
-// session (Railwatch::Sessions) join the browser side under one id.
-function startSession() {
+interface Store {
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+}
+
+// Where the session lives: localStorage, so every tab of the browser shares
+// one; sessionStorage when localStorage throws (storage disabled, a
+// sandboxed frame), which narrows the session to the tab; memory when both
+// throw, which narrows it to the page. The tab id lives in sessionStorage,
+// which survives a reload of the tab and nothing else, or in memory.
+let sessions: Store = memoryStore()
+let tabs: Store = memoryStore()
+
+function storage(kind: "localStorage" | "sessionStorage"): Store | undefined {
+  try {
+    const store = window[kind]
+    store.setItem("railwatch.probe", "1")
+    store.removeItem("railwatch.probe")
+    return store
+  } catch {
+    // Disabled, or denied to this frame. The caller tries the next one.
+    return undefined
+  }
+}
+
+function memoryStore(): Store {
+  const values = new Map<string, string>()
+  return {
+    getItem: (key) => values.get(key) ?? null,
+    setItem: (key, value) => void values.set(key, value),
+  }
+}
+
+// A full store throws on write. The session then lasts as long as this
+// page's memory of it, which is all a write could have bought.
+function save(store: Store, key: string, value: string) {
+  try {
+    store.setItem(key, value)
+  } catch {
+    // Quota exceeded.
+  }
+}
+
+// Mirrors the id into a cookie so every request the browser makes carries
+// it, full page loads included -- that is what lets the server side of the
+// session (Railwatch::Sessions) join the browser side under one id. It
+// lapses with the session's idle timeout, so the first page load after one
+// does not carry the dead id; every activity in any tab renews it.
+function remember(id: string) {
   try {
-    const existing = sessionStorage.getItem(SESSION_ID_KEY)
-    const id = existing ?? randomId()
-    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(),
-      })
+    document.cookie = `railwatch_session=${id}; path=/; max-age=${SESSION_TIMEOUT_MS / 1000}; SameSite=Lax`
+  } catch {
+    // A sandboxed frame has no cookies. Visits still carry the headers.
+  }
+}
+
+// A store that passed the probe can still throw later: the user turns
+// storage off, or the browser revokes it. From then on the page keeps its
+// own copy, seeded with the session it is in, so losing storage neither
+// stops the client nor ends the session.
+function read(key: string): string | null {
+  try {
+    return sessions.getItem(key)
+  } catch {
+    sessions = memoryStore()
+    if (session) {
+      sessions.setItem(SESSION_ID_KEY, session.id)
+      sessions.setItem(SESSION_STARTED_KEY, String(session.started_at))
+      sessions.setItem(SESSION_SEEN_KEY, String(session.seen))
+    }
+    return sessions.getItem(key)
+  }
+}
+
+function readTab(): string | null {
+  try {
+    return tabs.getItem(TAB_KEY)
   } catch {
-    // sessionStorage is unavailable (private mode, storage disabled).
-    // Everything else still reports; this tab just has no session.
+    tabs = memoryStore()
+    return null
   }
 }
 
-function beat(ended: boolean): Session | undefined {
+function startSession() {
+  sessions =
+    storage("localStorage") ?? storage("sessionStorage") ?? memoryStore()
+  tabs = storage("sessionStorage") ?? memoryStore()
+  tab = readTab() ?? randomId()
+  save(tabs, TAB_KEY, tab)
+  touch(true)
+}
+
+// Brings this tab's session up to date with the browser's, joining the one
+// another tab opened meanwhile. `active` is the user doing something -- the
+// page loading, a visit they wait on, the tab coming back into view -- which
+// keeps the session alive, or opens a new one when the last went 30 minutes
+// without activity in any tab or is 24 hours old. Anything else (a
+// background poll, a prefetch, a flush) only joins a live session, so a tab
+// left polling cannot hold its session open until the cap.
+function touch(active: boolean) {
+  const now = Date.now()
+  const id = read(SESSION_ID_KEY)
+  const seen = Number(read(SESSION_SEEN_KEY)) || 0
+  const startedAt = Number(read(SESSION_STARTED_KEY)) || 0
+  const live = id !== null && !expired(startedAt, seen, now)
+  if (live && id === session?.id) session.seen = Math.max(session.seen, seen)
+  else if (live) begin(id, startedAt, seen, false)
+  else if (active) begin(minted(id) ?? randomId(), now, now, true)
+  if (!active || !session) return
+  session.seen = now
+  save(sessions, SESSION_SEEN_KEY, String(now))
+  remember(session.id)
+}
+
+// The id the server put in the cookie for this browser's first page load
+// (Railwatch::Sessions.mint), so the session starts with that request rather
+// than after it. Not the session that just expired, whose id the cookie
+// can still hold.
+function minted(expiredId: string | null): string | undefined {
+  try {
+    const id = /(?:^|;\s*)railwatch_session=([A-Za-z0-9_-]{1,64})(?:;|$)/.exec(
+      document.cookie,
+    )?.[1]
+    return id && id !== expiredId && id !== session?.id ? id : undefined
+  } catch {
+    // A sandboxed frame has no cookies.
+    return undefined
+  }
+}
+
+function expired(startedAt: number, seen: number, now: number) {
+  return now - seen >= SESSION_TIMEOUT_MS || now - startedAt >= SESSION_CAP_MS
+}
+
+// The session this tab is in, while it is live. A background visit after it
+// timed out belongs to no session: it is neither tagged nor recorded as one.
+function liveSession(): string | undefined {
+  if (!session || expired(session.started_at, session.seen, Date.now()))
+    return undefined
+  return session.id
+}
+
+// Moves this tab into a session. The one it was in is over -- a session is
+// only replaced once it has timed out or reached the cap -- so this tab
+// says so with a last, `ended` beat. Closing a tab sends no such thing: the
+// browser's other tabs may still be in the session, and nothing a closing
+// tab knows says otherwise. A session no tab comes back to ends where the
+// server half's does, on its own timeout.
+function begin(id: string, startedAt: number, seen: number, minted: boolean) {
+  if (session)
+    post({
+      visits: [],
+      errors: [],
+      session: {
+        id: session.id,
+        started_at: session.started_at,
+        duration_ms: session.seen - session.started_at,
+        ended: true,
+      },
+      tenant: tenant(),
+    })
+  session = { id, started_at: startedAt, seen }
+  if (!minted) return
+  save(sessions, SESSION_ID_KEY, id)
+  save(sessions, SESSION_STARTED_KEY, String(startedAt))
+  save(sessions, SESSION_SEEN_KEY, String(seen))
+  // No duration on the first beat: that is what opens the session.
+  post({
+    visits: [],
+    errors: [],
+    session: { id, started_at: startedAt },
+    tenant: tenant(),
+  })
+}
+
+// While the session is live it runs to now, whichever tab is beating it. One
+// this tab has watched time out ran to its last activity, and is `ended`.
+function beat(): Session | undefined {
   if (!session) return undefined
-  return { ...session, duration_ms: Date.now() - session.started_at, ended }
+  const now = Date.now()
+  const ended = expired(session.started_at, session.seen, now)
+  return {
+    id: session.id,
+    started_at: session.started_at,
+    duration_ms: (ended ? session.seen : now) - session.started_at,
+    ended,
+  }
+}
+
+// Inertia sends a visit with whatever headers the visit object holds once
+// `before` has fired, so setting them here tags every visit, prefetch, poll
+// and partial reload with the session and the tab -- which is how a request
+// record joins its journey under the tab it came from. Only for the page's
+// own origin: a custom header makes a cross-origin request preflight, and
+// another origin is not this app's server anyway. The headers object is
+// replaced, not written into, because it may be the app's own options. The
+// prefetch cache compares headers; a prefetch and the click it serves are
+// tagged alike, so the prefetch still serves.
+function tag(visit: { url: unknown; headers?: Record<string, string> }) {
+  const id = liveSession()
+  if (!id) return
+  try {
+    if (new URL(String(visit.url), location.href).origin !== location.origin)
+      return
+  } catch {
+    // Not a URL Inertia could visit either.
+    return
+  }
+  visit.headers = {
+    ...visit.headers,
+    [SESSION_HEADER]: id,
+    [TAB_HEADER]: tab,
+  }
 }
 
 // --- Breadcrumbs -------------------------------------------------------
@@ -349,6 +549,8 @@ function capture(
     component,
     url: location.pathname + location.search,
     visit: current?.url,
+    session_id: liveSession(),
+    tab_id: tab,
     breadcrumbs: breadcrumbs.length > 0 ? breadcrumbs : undefined,
     context,
   }
@@ -755,6 +957,8 @@ function initialVisit(): Visit | null {
     duration_ms: duration,
     status: "success",
     ...ttfbPhases(nav),
+    session_id: liveSession(),
+    tab_id: tab,
   }
 }
 
@@ -774,7 +978,7 @@ function finalize() {
   }
   // Still flushes on every later hide: a tab can be backgrounded, brought
   // back, navigated some more, and then closed. Each of those carries a
-  // final session beat, which the platform dedupes by session id.
+  // session beat, which the platform dedupes by session id.
   flush(true)
 }
 
@@ -798,7 +1002,10 @@ export function startRailwatch(options: RailwatchOptions = {}) {
   // final there.
   router.on("before", (event) => {
     const v = event.detail.visit
-    if (!waiting(v) || event.defaultPrevented) return
+    if (event.defaultPrevented) return
+    touch(waiting(v))
+    tag(v)
+    if (!waiting(v)) return
     const request = (foregroundRequest = { id: idOf(v, "id") })
     queueMicrotask(() => {
       if (event.defaultPrevented && foregroundRequest === request)
@@ -817,6 +1024,8 @@ export function startRailwatch(options: RailwatchOptions = {}) {
       method: v.method,
       partial: Boolean(v.only?.length || v.except?.length),
       only: v.only,
+      session_id: liveSession(),
+      tab_id: tab,
     }
     crumb("navigate", `${v.method.toUpperCase()} ${current.url}`)
   })
@@ -847,6 +1056,7 @@ export function startRailwatch(options: RailwatchOptions = {}) {
   timer ??= window.setInterval(flush, 5000)
   document.addEventListener("visibilitychange", () => {
     if (document.visibilityState === "hidden") finalize()
+    else touch(true)
   })
   window.addEventListener("pagehide", finalize)
 }

data/lib/railwatch/configuration.rb

@@ -86,7 +86,7 @@ module Railwatch
                   :capture_job_arguments, :capture_job_retry_errors, :capture_response_body_on_error, :max_attachment_bytes,
                   :track_sessions, :session_flush_interval, :session_timeout,
                   :capture_console, :interactive_runner_paths, :ignored_request_paths,
-                  :capture_llm_content, :timing_headers
+                  :capture_llm_content, :timing_headers, :browser_client
 
     attr_reader :deploy, :deploy_source, :detect_deploy, :user_resolver, :beacon_user_resolver,
                 :fingerprint_resolver, :redactors, :rejectors, :before_ingest, :backpressure_high_water
@@ -245,6 +245,11 @@ module Railwatch
       # (#timing_headers?), since elsewhere they tell every visitor how the
       # app spends its time.
       @timing_headers = env_bool("RAILWATCH_TIMING_HEADERS", nil)
+      # Whether the app's pages run the browser client, which is what makes
+      # it safe to hand a first page load a session cookie (#browser_client?).
+      # nil: whether lib/railwatch.ts exists in the app's frontend source
+      # directory (Railwatch.frontend_dir), where railwatch:install puts it.
+      @browser_client = env_bool("RAILWATCH_BROWSER_CLIENT", nil)
       @user_resolver = nil
       @beacon_user_resolver = nil
       @fingerprint_resolver = nil
@@ -376,6 +381,22 @@ module Railwatch
       @timing_headers.nil? ? defined?(Rails) && Rails.env.development? : @timing_headers
     end
 
+    # Whether the browser client is installed (#browser_client). Looked for
+    # once, on the first request that asks, when Rails.root is known.
+    def browser_client?
+      return @browser_client unless @browser_client.nil?
+
+      @browser_client_installed = browser_client_installed? if @browser_client_installed.nil?
+      @browser_client_installed
+    end
+
+    def browser_client_installed?
+      return false unless defined?(Rails) && Rails.root
+
+      dir = Railwatch.frontend_dir(Rails.root)
+      dir ? Rails.root.join(dir, "lib/railwatch.ts").exist? : false
+    end
+
     # Matches Railwatch.reject_cache_keys entries and DEFAULT_VENDOR_CACHE_KEYS
     # against a cache key. A Regexp is used as-is. A String starting with "^"
     # or containing another regex metacharacter is compiled as a Regexp; a

data/lib/railwatch/middleware/request.rb

@@ -64,6 +64,7 @@ module Railwatch
         begin
           status, headers, body = @app.call(env)
           server_timing(env, exe, headers) if timing && headers
+          Sessions.mint(env, status, headers) if headers
         rescue Exception => e # rubocop:disable Lint/RescueException
           Subscribers::Exceptions.capture(e, handled: false, severity: :error, source: "railwatch.middleware")
           raise
@@ -202,7 +203,8 @@ module Railwatch
           payload: payload,
           queue_time: queue_time(env, exe),
           user_agent: req.user_agent.to_s[0, 256],
-          files: env["railwatch.files"] || uploaded_files_fallback(req, env)
+          files: env["railwatch.files"] || uploaded_files_fallback(req, env),
+          **Sessions.browser_fields(env)
         }
       end
 

data/lib/railwatch/sessions.rb

@@ -26,6 +26,18 @@ module Railwatch
     # a tab carries the id its beacons already use.
     COOKIE = /(?:\A|;\s*)railwatch_session=([^;]+)/
     KEY_LIMIT = 64
+    # What the browser client mints for a session or a tab id. Anything else
+    # in a header, cookie, or beacon is not one, and is not recorded as one.
+    BROWSER_ID = /\A[A-Za-z0-9_-]{1,64}\z/
+    # The id Sessions.mint handed this request, read by key_for and
+    # browser_fields as if the browser had sent it.
+    MINTED = "railwatch.session_id"
+    # The client's idle timeout, which the cookie lapses with (railwatch.ts).
+    COOKIE_MAX_AGE = 30 * 60
+    HTML = "text/html"
+    # A response a shared cache may store and serve to anyone. One visitor's
+    # cookie on it would be every visitor's.
+    SHARED_CACHE = /\b(?:public|s-maxage)\b/i
 
     @mutex = Mutex.new
     @wakeup = ConditionVariable.new
@@ -78,13 +90,61 @@ module Railwatch
     end
 
     # The browser client's id when the request carries one -- so the two
-    # halves of the same session share a key -- else the resolved user.
+    # halves of the same session share a key -- else the resolved user. A
+    # first page load the middleware minted an id for keys on that id, but
+    # only where it would have keyed on the user: an anonymous request with
+    # no cookie (a crawler, curl) opened no session before and opens none
+    # now. Its browser, if it runs the client, opens it with the first beat.
     def key_for(exe, env)
-      id = env["HTTP_X_RAILWATCH_SESSION"] || COOKIE.match(env["HTTP_COOKIE"])&.[](1)
+      id = sent_id(env)
       return id[0, KEY_LIMIT] unless id.nil? || id.empty?
 
       user = exe.user_id
-      user && "user:#{user}"[0, KEY_LIMIT]
+      return nil unless user
+      env[MINTED] || "user:#{user}"[0, KEY_LIMIT]
+    end
+
+    # The browser session and tab a request came from, for the request
+    # record: only what the browser client sent, never the user fallback
+    # above, which names a person rather than a session.
+    def browser_fields(env)
+      session = browser_id(sent_id(env) || env[MINTED])
+      tab = browser_id(env["HTTP_X_RAILWATCH_TAB"])
+      { session_id: session, tab_id: tab }.compact
+    end
+
+    def sent_id(env)
+      env["HTTP_X_RAILWATCH_SESSION"] || COOKIE.match(env["HTTP_COOKIE"])&.[](1)
+    end
+
+    # A browser's first page load carries no session cookie: the client sets
+    # it once the page runs, after this request is over. Without one the
+    # request would key on the user, a session no browser ever beats, and
+    # the journey would start a page late. So a page the client will run on
+    # -- a successful GET of an HTML document, not an Inertia visit, from an
+    # app with the client installed -- that arrives with no id gets one here,
+    # in the cookie the client reads and adopts. Never on a response a
+    # shared cache may keep (Cache-Control public or s-maxage).
+    def mint(env, status, headers)
+      return unless Railwatch.config.browser_client?
+      return unless env["REQUEST_METHOD"] == "GET" && status.to_i == 200
+      return if env["HTTP_X_INERTIA"] || sent_id(env)
+      return unless headers[Rack::CONTENT_TYPE].to_s.start_with?(HTML)
+      return if SHARED_CACHE.match?(headers[Rack::CACHE_CONTROL].to_s)
+
+      id = env[MINTED] = SecureRandom.hex(8)
+      # Secure over HTTPS (behind a TLS proxy too: ssl? reads
+      # X-Forwarded-Proto), so the id never rides a plain-HTTP request.
+      Rack::Utils.set_cookie_header!(headers, "railwatch_session",
+        { value: id, path: "/", max_age: COOKIE_MAX_AGE, same_site: :lax, secure: Rack::Request.new(env).ssl? })
+    rescue StandardError => e
+      # A frozen header hash: the client mints the id once the page runs.
+      env.delete(MINTED)
+      Railwatch.debug { "session cookie skipped: #{e.class}: #{e.message}" }
+    end
+
+    def browser_id(value)
+      value if value.is_a?(String) && BROWSER_ID.match?(value)
     end
 
     def emit(key, entry, ended)

data/lib/railwatch/version.rb

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

data/lib/railwatch/wire_fixtures.json

@@ -57,12 +57,16 @@
     "headers": {
       "Host": "www.example.com",
       "Accept": "text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5",
+      "X-Railwatch-Session": "3f2a9c1e7b4d6a08",
+      "X-Railwatch-Tab": "9e8d7c6b5a4f3e21",
       "Cookie": "[FILTERED]"
     },
     "payload": null,
     "queue_time": null,
     "user_agent": "",
-    "files": []
+    "files": [],
+    "session_id": "3f2a9c1e7b4d6a08",
+    "tab_id": "9e8d7c6b5a4f3e21"
   },
   "job_attempt": {
     "v": 1,
@@ -609,6 +613,8 @@
     "redirect_count": null,
     "connect_ms": null,
     "server_ms": null,
+    "session_id": "3f2a9c1e7b4d6a08",
+    "tab_id": "9e8d7c6b5a4f3e21",
     "user": null,
     "tenant": null,
     "user_agent": ""

data/lib/railwatch.rb

@@ -607,13 +607,28 @@ require "railwatch/subscribers"
 
 module Railwatch
   # The Inertia browser client, relative to the gem root. The install
-  # generator copies it into a host's app/frontend/lib.
+  # generator copies it into a host's frontend source directory, at lib/.
   BROWSER_CLIENT = "lib/generators/railwatch/install/templates/railwatch.ts"
+  # Where a Rails app keeps its Vite sources when ViteRuby does not say:
+  # vite_ruby's default, then the jsbundling/rails_vite one.
+  FRONTEND_DIRS = %w[app/frontend app/javascript].freeze
 
   def self.browser_client_path
     File.expand_path("../#{BROWSER_CLIENT}", __dir__)
   end
 
+  # The app's frontend source directory, relative to `root`: ViteRuby's
+  # configured sourceCodeDir when ViteRuby is loaded, else the first of
+  # FRONTEND_DIRS that exists, else nil. The install generator copies the
+  # client into it, and Configuration#browser_client? looks for it there.
+  def self.frontend_dir(root)
+    root = Pathname(root)
+    configured = defined?(ViteRuby) && (ViteRuby.config.source_code_dir rescue nil)
+    return configured.to_s if configured.present? && root.join(configured.to_s).directory?
+
+    FRONTEND_DIRS.find { |dir| root.join(dir).directory? }
+  end
+
   # One realistic wire record per record type, exactly as the gem's own
   # subscribers emit it, generated by spec/railwatch/wire_fixtures_spec.rb.
   # A receiver tests its mapper against these instead of hand-writing what

data/lib/tasks/railwatch_tasks.rake

@@ -144,21 +144,22 @@ namespace :railwatch do
     check.call(hook.exist? && hook.read.include?("railwatch"), "kamal post-deploy hook",
                hook.exist? ? hook.to_s : "not found (only needed when deploying with Kamal)")
 
-    client = Rails.root.join("app/frontend/lib/railwatch.ts")
+    frontend = Railwatch.frontend_dir(Rails.root) || "app/frontend"
+    client = Rails.root.join(frontend, "lib/railwatch.ts")
     check.call(client.exist?, "browser client",
                client.exist? ? "#{client} (call startRailwatch() from your Inertia entrypoint)" : "not found (only needed for Inertia visit timing)")
 
     # The client file existing is not the same as it running: startRailwatch()
     # has to be called from an entrypoint or no visit is ever timed.
-    entrypoints = Dir[Rails.root.join("app/frontend/entrypoints/*")].select { |f| File.file?(f) }
+    entrypoints = Dir[Rails.root.join(frontend, "entrypoints/*")].select { |f| File.file?(f) }
     started = entrypoints.select { |f| File.read(f).include?("startRailwatch") }
     check.call(started.any?, "browser client imported",
                if started.any?
                  started.map { |f| Pathname.new(f).relative_path_from(Rails.root).to_s }.join(", ")
                elsif entrypoints.any?
-                 "no entrypoint in app/frontend/entrypoints calls startRailwatch()"
+                 "no entrypoint in #{frontend}/entrypoints calls startRailwatch()"
                else
-                 "no app/frontend/entrypoints (only needed for Inertia visit timing)"
+                 "no #{frontend}/entrypoints (only needed for Inertia visit timing)"
                end)
 
     backend = Railwatch::Profiler.backend

metadata

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